The 4 Best Free Text Editors

Custom editors allow extensions to create fully customizable read/write editors that are used in place of VS Code's standard text editor for specific types of resources. They have a wide variety of use cases, such as:

• Previewing assets, such as shaders or 3D models, directly in VS Code.
• Creating WYSIWYG editors for languages such as Markdown or XAML.
• Offering alternative visual renderings for data files such as CSV or JSON or XML.
• Building fully customizable editing experiences for binary or text files.

This document provides an overview of the custom editor API and the basics of implementing a custom editor. We'll take a look at the two types of custom editors and how they differ, as well as which one is right for your use case. Then for each of these custom editor types, we'll cover the basics of building a well behaved custom editor.

Although custom editors are a powerful new extension point, implementing a basic custom editor is not actually that difficult! Still, if you are working on your first VS Code extension, you may want to consider holding off on diving into custom editors until you are more familiar with the basics of the VS Code API. Custom editors build on a lot of VS Code concepts—such as webviews and text documents—so it may be a bit overwhelming if you are learning all of these new ideas at the same time.

But if you're feeling ready and are thinking about all the cool custom editors you are going to build, then let's get started! Be sure to download the custom editor extension sample so you can follow along with the documentation and see how the custom editor API comes together.

Links

VS Code API Usage

Custom Editor API basics

A custom editor is an alternative view that is shown in place of VS Code's standard text editor for specific resources. There are two parts to a custom editor: the view that users interact with and the document model that your extension uses to interact with the underlying resource.

The view side of a custom editor is implemented using a webview. This lets you build the user interface of your custom editor using standard HTML, CSS, and JavaScript. Webviews cannot access the VS Code API directly but they can talk with extensions by passing messages back and forth. Check out our webview documentation for more information on webviews and best practices for working with them.

The other part of a custom editor is the document model. This model is how your extension understands the resource (file) it is working with. A uses VS Code's standard TextDocument as its document model and all changes to the file are expressed using VS Code's standard text editing APIs. and on the other hand let you provide your own document model, which lets them be used for non-text file formats.

Custom editors have a single document model per resource but there may be multiple editor instances (views) of this document. For example, imagine that you open a file that has a and then run the View: Split editor command. In this case, there is still just a single since there is still just a single copy of the resource in the workspace, but there are now two webviews for that resource.

vs

There are two classes of custom editors: custom text editors and custom editors. The main difference between these is how they define their document model.

A uses VS Code's standard as its data model. You can use a for any text based file types. are considerably easier to implement because VS Code already knows how to work with text files and can therefore implement operations such as save and backing up files for hot exit.

With a on the other hand, your extension brings its own document model. This means that you can use a for binary formats such as images, but it also means that your extension is responsible for a lot more, including implementing save and backing. You can skip over much of this complexity if your custom editor is readonly, such as custom editors for previews.

When trying to decide which type of custom editor to use, the decision is usually simple: if you are working with a text based file format use , for binary file formats use .

Contribution point

The contribution point is how your extension tells VS Code about the custom editors that it provides. For example, VS Code needs to know what types of files your custom editor works with as well as how to identify your custom editor in any UI.

Here's a basic contribution for the custom editor extension sample:

is an array, so your extension can contribute multiple custom editors. Let's break down the custom editor entry itself:

• - Unique identifier for your custom editor.

  This is how VS Code ties a custom editor contribution in the to your custom editor implementation in code. This must be unique across all extensions, so instead of a generic such as make sure to use one that is unique to your extension, for example

• - Name that identifies the custom editor in VS Code's UI.

  The display name is shown to the user in VS Code UI such as the View: Reopen with dropdown.

• - Specifies which files a custom editor is active for.

  The is an array of one or more glob patterns. These glob patterns are matched against file names to determine if the custom editor can be used for them. A such as will enable the custom editor for all PNG files.

  You can also create more specific patterns that match on file or directory names, for example .

• - (optional) Specifies when the custom editor is used.

  controls when a custom editor is used when a resource is open. Possible values are:

  • - Try to use the custom editor for every file that matches the custom editor's . If there are multiple custom editors for a given file, the user will have to select which custom editor they want to use.
  • - Do not use the custom editor by default but allow users to switch to it or configure it as their default.

Custom editor activation

When a user opens one of your custom editors, VS Code fires an activation event. During activation, your extension must call to register a custom editor with the expected .

It's important to note that is only called when VS Code needs to create an instance of your custom editor. If VS Code is merely showing the user some information about an available custom editor—such as with the View: Reopen with command—your extension will not be activated.

Custom Text Editor

Custom text editors let you create custom editors for text files. This can be anything from plain unstructured text to CSV to JSON or XML. Custom text editors use VS Code's standard TextDocument as their document model.

The custom editor extension sample includes a simple example custom text editor for cat scratch files (which are just JSON files that end with a file extension). Let's take a look at some of the important bits of implementing a custom text editor.

Custom Text Editor lifecycle

VS Code handles the lifecycle of both the view component of custom text editors (the webviews) and the model component (). VS Code calls out to your extension when it needs to create a new custom editor instance and cleans up the editor instances and document model when the user closes their tabs.

To understand how this all works in practice, let's work through what happens from an extension's point of view when a user opens a custom text editor and then when a user closes a custom text editor.

Opening a custom text editor

Using the custom editor extension sample, here's what happens when the user first opens a file:

1. VS Code fires an activation event.

   This activates our extension if it has not already been activated. During activation, our extension must ensure the extension registers a for by calling .

2. VS Code then invokes on the registered for .

   This method takes the for the resource that is being opened and a . The extension must fill in the initial HTML contents for this webview panel.

Once returns, our custom editor is displayed to the user. What is drawn inside the webview is entirely up to our extension.

This same flow happens every time a custom editor is opened, even when you split a custom editor. Every instance of a custom editor has its own , although multiple custom text editors will share the same if they are for the same resource. Remember: think of the as being the model for the resource while the webview panels are views of that model.

Closing custom text editors

When a user closes a custom text editor, VS Code fires the event on the . At this point, your extension should clean up any resources associated with that editor (event subscriptions, file watchers, etc.)

When the last custom editor for a given resource is closed, the for that resource will also be disposed provided there are no other editors using it and no other extensions are holding onto it. You can check the property to see if the has been closed. Once a is closed, opening the same resource using a custom editor will cause a new to be opened.

Synchronizing changes with the TextDocument

Since custom text editors use a as their document model, they are responsible for updating the whenever an edit occurs in a custom editor as well as updating themselves whenever the changes.

From webview to

Edits in custom text editors can take many different forms—clicking a button, changing some text, dragging some items around. Whenever a user edits the file itself inside the custom text editor, the extension must update the . Here's how the cat scratch extension implements this:

1. User clicks the Add scratch button in the webview. This posts a message from the webview back to the extension.

2. The extension receives the message. It then updates its internal model of the document (which in the cat scratch example just consists of adding a new entry to the JSON).

3. The extension creates a that writes the updated JSON to the document. This edit is applied using .

Try to keep your workspace edit to the minimal change required to update the document. Also keep in mind that if you are working with a language such as JSON, your extension should try to observe the user's existing formatting conventions (spaces vs tabs, indent size, etc.).

From to webviews

When a changes, your extension also needs to make sure its webviews reflect the documents new state. TextDocuments can be changed by user actions such as undo, redo, or revert file; by other extensions using a ; or by a user who opens the file in VS Code's default text editor. Here's how the cat scratch extension implements this:

1. In the extension, we subscribe to the event. This event is fired for every change to the (including changes that our custom editor makes!)

2. When a change comes in for a document that we have an editor for, we post a message to the webview with its new document state. This webview then updates itself to render the updated document.

It's important to remember that any file edits that a custom editor triggers will cause to fire. Make sure your extension does not get into an update loop where the user makes an edit in the webview, which fires onDidChangeTextDocument, which causes the webview to update, which causes the webview to trigger another update on your extension, which fires , and so on.

Also remember that if you are working with a structured language such as JSON or XML, the document may not always be in a valid state. Your extension must either be able gracefully handle errors or display an error message to the user so that they understand what is wrong and how to fix it.

Finally, if updating your webviews is expensive, consider debouncing the updates to your webview.

Custom Editor

and let you create custom editors for binary file formats. This API gives your full control over the file is displayed to users, how edits are made to it, and lets your extension hook into and other file operations. Again, if you are building an editor for a text based file format, strongly consider using a instead as they are far simpler to implement.

The custom editor extension sample includes a simple example custom binary editor for paw draw files (which are just jpeg files that end with a file extension). Let's take a look at what goes into building a custom editor for binary files.

CustomDocument

With custom editors, your extension is responsible for implementing its own document model with the interface. This leaves your extension free to store whatever data it needs on a in order to your custom editor, but it also means that your extension must implement basic document operations such as saving and backing up file data for hot exit.

There is one per opened file. Users can open multiple editors for a single resource—such as by splitting the current custom editor—but all those editors will be backed by the same .

Custom Editor lifecycle

supportsMultipleEditorsPerDocument

By default, VS Code only allows there to be one editor for each custom document. This limitation makes it easier to correctly implement a custom editor as you do not have to worry about synchronizing multiple custom editor instances with each other.

If your extension can support it however, we recommend setting when registering your custom editor so that multiple editor instances can be opened for the same document. This will make your custom editors behave more like VS Code's normal text editors.

Opening Custom Editors When the user opens a file that matches the contribution point, VS Code fires an activation event and then invokes the provider registered for the provided view type. A has two roles: providing the document for the custom editor and then providing the editor itself. Here's a ordered list of what happens for the editor from the custom editor extension sample:

1. VS Code fires an activation event.

   This activates our extension if it has not already been activated. We must also make sure our extension registers a or for during activation.

2. VS Code calls on our or registered for editors.

   Here our extension is given a resource uri and must return a new for that resource. This is the point at which our extension should create its document internal model for that resource. This may involve reading and parsing the initial resource state from disk or initializing our new .

   Our extension can define this model by creating a new class that implements . Remember that this initialization stage is entirely up to extensions; VS Code does not care about any additional information extensions store on a .

3. VS Code calls with the from step 2 and a new .

   Here our extension must fill in the initial html for the custom editor. If we need, we can also hold onto a reference to the so that we can reference it later, for example inside commands.

Once returns, our custom editor is displayed to the user.

If the user opens the same resource in another editor group using our custom editor—for example by splitting the first editor—the extension's job is simplified. In this case, VS Code just calls with the same we created when the first editor was opened.

Closing Custom Editors

Say we have two instance of our custom editors open for the same resource. When the user closes these editors, VS Code signals our extension so that it can clean up any resources associated with the editor.

When the first editor instance is closed, VS Code fires the event on the from the closed editor. At this point, our extension must clean up any resources associated with that specific editor instance.

When the second editor is closed, VS Code again fires . However now we've also closed all the editors associated with the . When there are no more editors for a , VS Code calls the on it. Our extension's implementation of must clean up any resources associated with the document.

If the user then reopens the same resource using our custom editor, we will go back through the whole , flow with a new .

Readonly Custom editors

Many of the following sections only apply to custom editors that support editing and, while it may sound paradoxical, many custom editors don't require editing capabilities at all. Consider a image preview for example. Or a visual rendering of a memory dump. Both can be implemented using custom editors but neither need to be editable. That's where comes in.

A lets you create custom editors that do not support editing. They can still be interactive but don't support operations such as undo and save. It is also much simpler to implement a readonly custom editor compared to a fully editable one.

Editable Custom Editor Basics

Editable custom editors let you hook in to standard VS Code operations such as undo and redo, save, and hot exit. This makes editable custom editors very powerful, but also means that properly implementing is much more complex than implementing an editable custom text editor or a readonly custom editor.

Editable custom editors are implemented by . This interface extends , so you'll have to implement basic operations such as and , along with a set of editing specific operations. Let's take a look at the editing specific parts of .

Edits

Changes to a editable custom document are expressed through edits. An edit can be anything from a text change, to an image rotation, to reordering a list. VS Code leaves the specifics of what an edit does entirely up to your extension, but VS Code does need to know when an edit takes places. Editing is how VS Code marks documents as dirty, which in turn enables auto save and back ups.

Whenever a user makes an edit in any of the webviews for your custom editor, your extension must fire a event from its . The event can fired two event types depending on your custom editor implementation: and .

CustomDocumentContentChangeEvent

A is a bare-bones edit. It's only function is to tell VS Code that a document has been edited.

When an extension fires a from , VS Code will mark the associated document as being dirty. At this point, the only way for the document to become non-dirty is for the user to either save or revert it. Custom editors that use do not support undo/redo.

CustomDocumentEditEvent

A is a more complex edit that allows for undo/redo. You should always try to implement your custom editor using and only fallback to using if implementing undo/redo is not possible.

A has the following fields:

• — The the edit was for.
• — Optional text that that describes what type of edit was made (for example: "Crop", "Insert", ...)
• — Function invoked by VS Code when the edit needs to be undone.
• — Function invoked by VS Code when the edits needs to be redone.

When an extension fires a from , VS Code marks the associated document as being dirty. To make the document no longer dirty, a user can then either save or revert the document, or undo/redo back to the document's last saved state.

The and methods on an editor are called by VS Code when that specific edits needs to be undone or reapplied. VS Code maintains an internal stack of edits, so if your extension fires with three edits, let's call them , , :

The following sequence of user actions results in these calls:

To implement undo/redo, your extension must update it's associated custom document's internal state, as well as updating all associated webviews for the document so that they reflect the document's new state. Keep in mind that there may be multiple webviews for a single resource. These must always show the same document data. Multiple instances of an image editor for example must always show the same pixel data but may allow each editor instance to have its own zoom level and UI state.

Saving

When a user saves a custom editor, your extension is responsible for writing the saved resource in its current state to disk. How your custom editor does this depends largely on your extension's type and how your extension tracks edits internally.

The first step to saving is getting the data stream to write to disk. Common approaches to this include:

• Track the resource's state so that it can be quickly serialized.

  A basic image editor for example may maintain a buffer of pixel data.

• Replay edit since the last save to generate the new file.

  A more efficient image editor for example might track the edits since the last save, such as , , . On save, it would then apply these edits to file's last saved state to generate the new file.

• Ask a for the custom editor for file data to save.

  Keep in mind though that custom editors can be saved even when they are not visible. For this reason, it is recommended that that your extension's implementation of does not depend on a . If this is not possible, you can use the setting so that the webview stays alive even when it is hidden. does have significant memory overhead so be conservative about using it.

After getting the data for the resource, you generally should use the workspace FS api to write it to disk. The FS APIs take a of data and can write out both binary and text based files. For binary file data, simply put the binary data into the . For text file data, use to convert a string into a :

Next steps

If you'd like to learn more about VS Code extensibility, try these topics:

9/1/2022

From a general perspective, while looking at text editors for macOS 10.14, we are not specifically referring to the text as we have it in the document text. A large chunk of text editors on the market, particularly those that offer greater capabilities, will turn out to also come with extremely robust features for code compiling. This is where their true potential lies. Today, we will look at the 10 best free text editors on macOS 10.14.

Top 10 Free Text Editors for macOS 10.14

1. Brackets

This is a free text editor macOS 10.14 that is open source and maintained by Adobe Systems — one of the major companies in the industry. One of the outstanding features of Brackets is its beautiful interface. Its unique Extract offering lets you grab font, gradients measurements, and so on from a PSD file into a CSS that is clean and ready for use on the web.

Pros

• It comes with extension support which contains a huge and growing library.
• Brackets have inline editors and previews.

Cons

• It is slow
• Brackets still do not have certain elementary text editor commands
• Its updater is problematic

Free Download Brackets

2. TextWrangler

Developed by Bare Bones, TextWrangler is another best text editor on macOS 10.14. This tool can be regarded as a lightweight version of BBEdit, also designed by Bare Bones. It has all the features needed by hardcore developers to carry out operations in specific columns in a CSV, or in a server admin for scriptwriting.

Pros

• It offers basic text editing as well as manipulations.
• TextWrangler is a free yet ideal alternative to BBEdit.
• It has an inbuilt FTP or STFP browser.
• It is robust and fast to start up.

Cons

• It isn’t maintained any longer.

Free Download TextWrangler

3. Vim

This software is a command line-based text editor for macOS 10.14. One of the most renowned text editors on the market, Vim does not have a steep learning curve. It features a stack of documentation that assists a user in learning how to use the app conveniently. Vim is designed with a quick reference, help documents, along a tutorial that runs for 30 minutes to get you acquainted with it.

Pros

• It has capabilities and features for command-based text editing.
• It is easy to use

Cons

• Vim requires great effort to customize.
• It offers poor support for external tooling.

Free Download Vim

4. Komodo Edit

It is an open-source text editor on macOS 10.14 that is free and offers a powerful user interface. Komodo Edit is a fantastic tool for writing code and carrying out other operations. The software provides many useful tools, which help you edit, like the capacity of tracking changes, multiple sections, autocomplete, and skin and icon sets.

Pros

• It is an extremely professional and comprehensive tool.
• It has inbuilt FTP.
• Free and open-source, Komodo Edit supports a limited Vim mode.

Cons

• It isn’t very lightweight.
• It includes project files to project code.

Free Download Komodo Edit

5. Sublime Text

Though this app is a commercial text editor to create text file macOS 10.14, it has an evaluation version that can be used for an unlimited period; this makes it free in reality. Sublime Text features a Python Application Programming Interface and allows multiple languages. Furthermore, the software’s capabilities can be enhanced with the aid of plugins, which are often developed by communities and offered via free software licenses.

Pros

• Sublime Text comes with an easy-to-use interface.
• There are 22 different themes you can select from.
• It has a distraction-free mode, consisting of placing only the text on your screen.

Cons

• It does not allow the printing of files.
• Sublime Text 10.14 has inadequate language support.
• It takes time to load large files on Windows.

Free Download Sublime Text

6. Atom

This is another free text editor macOS 10.14 that is written in Node.js as well as embedded in GitControl. Atom can be employed either as a plain text editor or as a source code editor. By using plug-ins, the software works well in several languages, including HTML, Objective-C, C/C++, CSS, Java, Go, JavaScript, C#, PHP, Python, and many others. This makes it a versatile tool for a lot of developers.

Pros

• It allows multi-tabbed editing, multiple panes, and auto-completion.
• The software offers a user interface that is friendly.

Cons

• It does not have text UI.
• It is extremely slow to start up.

Free Download Atom

7. TextMate

TextMate basically employs the extremely robust capabilities of the UNIX command console in a user-friendly and neat GUI. This provides you with the best of the two worlds — as a committed programmer or a beginner code user. TextMate integrates features such as auto-indentation, search and replace within the project, dynamic outlines, column selection, among others.

Pros

• The program features an extensive library of plugins.
• It is free and open-source.

Free Download TextMate

8. GNU Emacs

Emacs, first launched in 1976, is popular for its unique techniques for getting the job done. It employs a programming language called Emacs-Lisp, which has the most fundamental functions of editing for expanding the capabilities of the program beyond its humble text-based origin. Some of these expansions are an email client, file manager, newsreader as well as games such as Tetris and Snake.

Pros

• It can be entirely controlled using the keyboard.
• It lets you debug, manage files, and compile.

Cons

• It has a long learning curve.
• Its extensibility can, occasionally, be a source of distraction to your work.

Free Download Emacs

9. Visual Studio Code

Compared to other text editing apps, this software is a newcomer. It is a lightweight text and script editor that, along with many other spectacular features, comes with a dark theme. If you do not like text editors like Vim and Emacs, Visual Studio Code is a perfect alternative.

Pros

• Visual Studio Code offers JavaScript IntelliSense support.
• It has a lot of plugins for enhancing its functionality.
• The software features integrated Git control, data integrity, and support for distributed and non-linear workflows.

Cons

• Its autocomplete, as well as code check offerings, aren’t as robust as those of WebStorm.
• Visual Studio Code has a terrible auto import.

Free Download Visual Studio Code

10. UltraEdit

Developed by IDM Computer Solutions, UltraEdit is a great program that works with remote files perfectly. It isn’t only fast but also stable and easy to use. It handles big files efficiently of sizes over 1GB. UltraEdit comes with an array of features that help you in carrying out operations such as highlighting of syntax, sorting of file or data, editing of column or block, and so on. The software also supports SSH/telnet.

Pros

• UltraEdit works very well with large files.
• It is easy to use and fast.

Cons

• The themes that were released in version 20 had an adverse effect on specific aspects of syntax coloring.

Free Download UltraEdit

Best Free All-in-One PDF Editor for macOS 10.14

PDFelement for Mac is an all-in-one PDF File Management program for macOS 10.14 with versatile tools for editing documents in Portable Document Format. This is the best app for you to carry out operations like editing, cutting, copying, pasting, and deleting PDF files. It also helps you include text and pictures in PDF documents. PDFelement allows you to modify font attributes like size type and style.

Other features:

• PDFelement for Mac lets you insert, remove and update custom watermarks as well as backgrounds.
• You can use the app for inserting, updating, or removing headers as well as footers.
• This software is an excellent annotator and document converter.
• It helps you insert as well as edit hyperlinks.
• The program allows you to generate and manage a library containing pre-built and custom stamps.
• You can use PDFelement for Mac to create and edit fillable PDF forms.
• It lets you fill in PDF forms.
• The software offers support to create, edit, and include digital signatures on documents in PDF.
• It supports processing PDF documents in dark mode.

Free Download or Buy PDFelement right now!

Free Download or Buy PDFelement right now!

Buy PDFelement right now!

Buy PDFelement right now!

File Viewer Plus is a universal file viewer and converter that supports over 400 different types of files, including documents, spreadsheets, images, audio and video, and many more. With one program, you can view and convert hundreds of file types without installing any other software.

File Viewer Plus also comes with advanced editing and conversion features. It includes a professional-quality word processor, a spreadsheet editor, and an image editor. You can convert individual files or thousands of files at once using the built-in batch converter.

The application is also an advanced file utility. It includes a file information panel that displays file metadata for every file you open. The file inspector allows you to see the raw contents of any file text or hexadecimal format. In the rare case File Viewer Plus does not support a certain file format, the intelligent file identification algorithm provides as much information as possible about the file.

GPU Rendering

Sublime Text can now utilize your GPU on Linux, Mac and Windows when rendering the interface. This results in a fluid UI all the way up to 8K resolutions, all while using less power than before.

Apple Silicon and Linux ARM64

Sublime Text for Mac now includes native support for Apple Silicon processors. Linux ARM64 builds are also available for devices like the Raspberry Pi.

Tab Multi-Select

File tabs have been enhanced to make split views effortless, with support throughout the interface and built-in commands. The side bar, tab bar, Goto Anything, Goto Definition, auto complete and more have all been tweaked to make code navigation easier and more intuitive than ever.

Context-Aware Auto Complete

The auto complete engine has been rewritten to provide smart completions based on existing code in a project. Suggestions are also augmented with info about their kind, and provide links to definitions.

Refreshed UI

The Default and Adaptive themes have been refreshed with new tab styles and inactive pane dimming. Themes and Color Schemes support auto dark-mode switching. The Adaptive theme on Windows and Linux now features custom title bars.

TypeScript, JSX and TSX Support

Support for one of the most popular new programming languages is now shipped by default. Utilize all of the smart syntax-based features of Sublime Text within the modern JavaScript ecosystem.

Superpowered Syntax Definitions

The syntax highlighting engine has been significantly improved, with new features like handling non-deterministic grammars, multi-line constructs, lazy embeds and syntax inheritance. Memory usage has been reduced, and load times are faster than ever.

Updated Python API

The Sublime Text API has been updated to Python 3.8, while keeping backwards compatibility with packages built for Sublime Text 3. The API has been significantly expanded, adding features that allow plugins like LSP to work better than ever. Read the revamped documentation here.

Meet the Sublime Family

References

• References are created by right clicking in the diagram selecting over which participants the reference should be from the menu
• Edit the text of a reference by double clicking it
• Change the start and end participants of the reference by clicking and dragging the start or end of the reference
• Change position of the reference by clicking and dragging the middle of the note or box
  • Note: It is the bottom of the shapes that counts as the y position when dragging
• Delete the reference by clicking it and pressing the delete key
• New line is create using \n

⎘

A->B:info ref over B,C:other interaction C->D:info

Dividers

• Dividers are created by right clicking in the diagram and selecting the divider entry from the menu
• Edit the text of a divider by double clicking it
• Change position of the divider by clicking and dragging it
• Delete the divider by clicking it and pressing the delete key

⎘

participant A participant B participant C participant D ==info==

Create and Destroy

• Create and destroy are at this point not part of the context menu, participants may be defined in the start of the diagram
  • participantNameA->*participantNameB: message: Sends a message to participantNameB and creates participantNameB
  • create participantName: Creates the participant without sending a message to it
  • destroy participantName: Destroys the participant at the previous entry's y position
  • destroyafter participantName: Destroys the participant at after a space and gives the destroy symbol its own space
  • destroysilent participantName: Destroys the participant at the previous entry's y position without rendering the destroy symbol
• Click and drag on the entries to move them in y axis using the mouse

⎘

participant A actor X participant B A->B:info B-->*C:<<create>> note over C:do something B<-C:info destroy C B->*X:message to X note over X:do something destroyafter X A->B:info

⎘

A->B:info create C note over C: C created without message A<-C:info

⎘

A->>B:request A<<--B:response destroysilent B destroysilent A C->D: info

Activations

• Activations are created by right clicking in the diagram and selecting the activation entry from the menu
  • activate participantName: Activates the participant at the previous entry's y position
  • deactivate participantName: Deactivates the participant at the previous entry's y position. If no entry has been added since the activation the activity is deactivated directly, use deactivateafter or space if you want an empty gap
  • deactivateafter participantName: Deactivates the participant right below the previous entry's y position
• Activations cannot be selected, moved, or edited using the mouse

⎘

participant A participant B participant C participant D A->B:info activate B B->C:info activate C C->>D:info activate D B<--C:info deactivate C A<--B:info deactivate B B<-D:callback deactivate D activate B A<<--B:info deactivate B

⎘

participant B participant D activate D B->D:info activate B deactivateafter B D->D:info activate D space deactivate D

⎘

activate Alice Alice->Alice:privateMethod() activate Alice Alice<<--Alice:returnValue deactivate Alice Alice->Alice:privateMethod() activate Alice Alice<<--Alice:returnValue deactivateafter Alice

Auto Activation

• Auto Activation automatically create activations on request messages and deactives on response messages, usual activations and deactivations can be used in combination with automatic activation
  • autoactivation on: Activates automatic activations
  • autoactivation off: Deactivates automatic activations

⎘

autoactivation on A->B:info B->C:info B<-C:info B-->C:info B->B:info deactivateafter B B<--C:info A<--B:info autoactivation off A->B:info A<--B:info

Spaces

• Spaces are created by right clicking in the diagram and selecting the space entry from the menu, examples:
  • space
  • space 3
  • space -4 (may be used in together with non-instantaneous messages to visualize messages being sent out earlier arriving after later messages)
• Change position of the space by clicking and dragging it
• Delete the space by clicking it and pressing the delete key

⎘

participant B participant D activate D B->D:info activate B space 3 deactivate B D->D:info activate D space deactivate D

Fragments

• Fragments are created by right clicking in the diagram and selecting the wanted fragment type from the menu
  • Since many possible fragments exists, only the most common are included in the menu, complete list: alt, opt, loop, par, break, critical, ref, seq, strict, neg, ignore, consider, assert, region
• Special fragments
  • group allows a custom label for the fragment
  • expandable allows a portion of the diagram to be expanded (expandable-) and collapsed (expandable+), click the label to toggle the expandable
• Edit the text of a fragment by double clicking the top of the fragment or its else part
• Change inclusion of entries by clicking and dragging top, bottom, or else part of the fragment
• You can also create new items directly inside the fragment
• Delete the whole fragment (but keep the contents) by clicking the top or bottom of the fragment and pressing the delete key
• Delete only the else (else is only supported inside the alt fragment) part by clicking the else divider and pressing delete key

⎘

opt optional note over A:info A->B:info end

⎘

alt case 1 A->B:info else case 2 A->B:info else case 3 A->B:info end

⎘

loop i < 1000 note over A:info A->B:info end

⎘

par info A->B:info1 thread test A->B:info2 thread test A->B:info2 end

⎘

par info A->C:info A->B:info end

⎘

group own name A->B:info end group own name [some text] A->B:info end

⎘

A->B:info1 expandable- info 1234567890 B->C:info2 C->D:info3 D->E:info4 end E->F:info5 expandable+ info qwertyurtyuiortyuioasdfghjkwertyuio B->C:info2 C->D:info3 D->E:info4 end

Participant Groups

• Participant Groups are at this point not part of the context menu
• Participant Groups draws a box to encompass a set of participants
• Multiple nested levels are supported

⎘

participantgroup #lightgreen **Group 1** participant A participant B end participantgroup #lightblue **Long\nname** participant C end B->C:info note over A,B:info

⎘

participantgroup #lightgreen **Group 1** participantgroup #grey sub1 participant A end participantgroup #pink sub2 participant B end end participantgroup #lightblue **Long\nname** participant C end B->C:info note over A,B:info

Links

• Links can be added to all entries with text
• Links can be clicked in the diagram (opens a new window) and are included when the diagram is exported as an SVG document

⎘

A->B:This text contains a <link:http://example.com>link</link> note right of B:Here is <link:https://www.w3schools.com>another link</link>

⎘

participant "Participant with a <link:http://example.com>link</link>" as Alice Alice->Bob:info

Frame

• Frame draws a frame to encompass the entire diagram

⎘

frame Example Diagram A->B:info C->A: info note over B,C:info

⎘

frame #red Example Diagram A->B:info C->A: info note over B,C:info

Text Styling

• Text in all entries can be styled
• Bold text: **some bold text**
• Italic text: //some italic text//
• Small text: --some small text--
• Big text: ++some big text++
• Monospaced text: ""some big text""
• Strike through text: ~~some big text~~
• Big and bold: ++**some big and bold text**++
• Italic and small: //--italic and small--//
• Use \ to escape wanted */-+ chars, examples: c\+\+ http:\/\/www.example.org
• Color: <color:#red>red text</color>
• Aligned text: <align:center>some centered text</align>
• Sized text: <size:20>some very large text</size>
• Stroke: <stroke:5:#red>text stroked with weight 5</stroke>
• Background: <background:#red>text with background</background>
• Difference: <difference>inverse text color for high contrast, use in combination with text color #white</difference>

⎘

box over A:**some bold text** box over A://some italic text// box over A:--some small text-- box over A:++some big text++ box over A:++**Big and bold\nlines of text**++\n//--italic and small--//

⎘

participant "Al<color:#red>ice</color>//**Long** ++name++//" as Alice box over Alice:Com<color:#00ff00>binations:\n++**Big and bold green\nlines of text**++\n//--ital</color>ic and small--//\n++Writing C\+\+ in big text using \ to escape +++

⎘

note over A:""This is mono spaced""

⎘

note over Bob:<size:20>infoinfo</size><size:10>infoinfo</size>

⎘

note over Alice:<align:left>infoinfoinfo\ninfo</align> note over Alice:<align:center>infoinfoinfo\ninfo</align> note over Alice:<align:right>infoinfoinfo\ninfo</align>

⎘

participant "Long ~~strikethrough~~ name" as Alice Alice->Bob:Click and ~~drag to create a request~~ or\ntype it in the source area to the left

⎘

participantgroup #gray <color:#white>Group</color> participant A participant B end A->B:<stroke:1.5:#white><color:#black>stroke text 1</color></stroke> A->B:<stroke:1:#lightgreen><color:#white>++**stroke text 2**++</color></stroke>

⎘

participant "<background:#yellow>AAAAAAAAAA</background>" as A participant B A->B:<background:#yellow>background</background> no background

⎘

participantgroup #darkblue participant AAAAAAAAAAAAAA end participantgroup #black participant CCCCCCCCCCCCCC end AAAAAAAAAAAAAA->CCCCCCCCCCCCCC:<difference><color:#white>abcdefghijklmnopqrstuvwxy</color></difference>

Colors

• Color is supported for most of the entries and use the HTML color names or hex
• W3C provides a good list of color names: W3C color names
• Examples: #ff00ff, #lightblue

⎘

participant A#red database B#green

⎘

participant A participant B participant C participant D ==info==#lightgreen

⎘

note over A#yellow:info rbox over A#violet:info abox right of A#steelblue:info

⎘

A-#red>B:info A<#green--B:info A--#blue>>B:info

⎘

participant A participant B activate A #00ee77 A->B:info activate B #red B->B:info activate B #lightgray deactivateafter B

⎘

loop #ff00ff info 1234567890 B->C:info2 C->D:info3 D->E:info4 end

⎘

group #2f2e7b label text #white [condition] A->B:info end loop #2f2e7b #white condition A->B:info end

Active Color

• Active color specifies the color of all activations of a participant, the specified value will be overridden by any color specified on specific activations
  • activecolor #red: make all activations red
  • activecolor participantName #blue: make all activations of the participant blue

⎘

participant B participant C participant D activecolor #red activecolor C #blue activate B B->C:info activate C C->>D:info activate D B<--C:info deactivate C deactivate B B<-D:callback activate C deactivate D activate B B->D:info deactivate B B<-D:info activate B #green

Fonts

• The font can be specified using the fontfamily keyword and the css name of the font
• Specific font: fontfamily My Font Name
• Browser selected sans-serif font: fontfamily sans-serif
• Browser selected mono spaced font: fontfamily mono

⎘

fontfamily mono participant A note over A:This is mono spaces

Automatic Numbering

• The autonumber statement gives automatic number of subsequent messages
• The autonumber off statement stops the numbering
• Automatic numbering can be started at a specified number, example: autonumber 10

⎘

autonumber 1 A->B:info B->B:info autonumber 10 C->D:info A<-B:info A->B:info autonumber off B->C:info C->D:info

Linear Messages

• The linear statement makes subsequent messages of the same type linear
• The linear off statement stops linear

⎘

linear A->B:info B->C:info C->D:info C<--D:info B<--C:info A<--B:info A->>B:info B->>C:info linear off C->>D:info

Parallel

• The parallel statement simply puts subsequent entries at the same y position
• The parallel off statement stops parallel
• It is different from linear since it doesn't do any intelligent matching for different types of entries

⎘

parallel A<<-B:info B->C:info note left of D:info parallel off C->>D:info

Participant Spacing

• Participant spacing allows control of spacing between the participants
• The participantspacing equal statement makes the spacing between all participants equal
• The participantspacing 50 statement makes the spacing between all participants at least 50

⎘

participantspacing equal participant A participant B participant C A->B:info info info

Entry Spacing

• Entry spacing allows control of spacing between the entries
• Click anywhere on the diagram and press the + or - key to change spacing between all entries
• Add entryspacing statements to change in different places of the diagram

⎘

entryspacing 0.1 A->B:info A->B:info entryspacing 3 A->B:info entryspacing 1 A->B:info A->B:info

Life Line Style

• Specifies the style of the life lines
  • lifelinestyle #blue - make all life lines blue
  • lifelinestyle participantName #red - make participant life line red
  • lifelinestyle :4 - make all life line weights 4
  • lifelinestyle C #gray:1:solid - make participant life line gray, line weight 1, solid

⎘

participant A participant B participant C participant D lifelinestyle #red:4:solid lifelinestyle B #black:1:dashed lifelinestyle C #gray:1:solid lifelinestyle D ::dashed A->B:info B->C:info C->D:info

Large Example

• Large example including most of the features

⎘

Source too large to display