How to enter text

Use the text area at the bottom of the window to specify your objects and messages. The object section must be separated from the message section by an empty line.

Should there be a (syntax) error in your text, the first line where such an error occurs is highlighted. And there will be a description of the error at the bottom of the window.

'.' and ':' will not be interpreted as delimiters, if they are preceded by a '\'.

Objects

For each object you want to appear in your sequence diagram, type 

<name>:<Type>[<flags>] "<label>"

or

/<name>:<Type>[<flags>] "<label>"

into the text area. This represents an instance of class <Type>, named <name> which will be shown as a lifeline. <name>. The [<flags>] and "<label>" parts are optional:

If you specify a quoted label, it will be used to label the object with, otherwise the object's label will be derived from the name and the type.

Invisible objects

If <name> is prefixed with a '/', the lifeline will be invisible until the instance is created by a 'new' message to <name> (see below).

Flags

An object declaration can be followed by a sequence of <flags> between square brackets. Four flags (a,p,r,x) are supported:

a-nonymous

The object is anonymous, so the name (which must still be there in order to be able to reference the lifeline) will not appear on the diagram, just a colon followed by the type. This flag is useless if a <label> is specified.

r-ole

The label of the lifeline will not be underlined.

p-rocess

The object behaves like an actor (see below), but it is represented by a box with a thick border, not by a figure.

e-external

(Only) a process can be declared to be external, which means that it represents an external entity with the ability to send "found" messages, but not appearing on the diagram. Messages originating from an external process are represented by arrows starting with filled circles.

x-auto-destruction

The object is destroyed when it has sent its last answer, denoted by a cross below its lifeline. One might interpret this as automatic destruction of non-persistent objects by a garbage collector.

There are other flags, relevant for multithreading .

Actors

If <Type> is 'Actor', the lifeline belongs to an actor. An actor is always active and sends asynchronous messages. It cannot send messages to itself. Also, it cannot receive answers (see below). In order to send an answer to an actor, one must use an explicit message.

Messages

The lines in the message section have the following format: 

<caller>[<s>]:<answer>=<callee>[m].<message>

<caller> is the name of an object that has been declared in the object section. It is either the first one to send a message or has received a message before and not yet answered to it. Otherwise it is not active and cannot send a message.

[<s>] is optional and refines the specification of the caller object.

If <s> is a number, it denotes the 'level' of the caller: A caller may have received k messages to which it has yet to answer. Then <s> can range from 0 to k-1. Before <caller> sends the message, it will answer to the <s> most recent messages.

If <s> is not a number, it is a mnemonic. A mnemonic can be defined for a callee (by using the optional [<m>] part). If <s> is a mnemonic that has been defined for the object <caller> and <caller> is still active, <caller>[<s>] references this object.

<answer>= is optional and <answer> is simply a string representing the answer to the message. This string is used as a label of a dashed arrow from the <callee> to the <caller> lifeline. Note that there cannot be answers to messages sent by and to actors.

<callee>. is optional and <callee> denotes the object that receives the message represented by the string <message>, which is used as a label of an arrow from <caller> to <callee>. If no <callee> is specified, <message> is interpreted as an description of a simple action (not another invocation of a method/procedure) performed by the caller.

[<m>] is optional and <m> is a mnemonic containing at least one character that is not a digit. As long as the callee is active, it can be referenced as a caller by its name followed by [<m>].

<message> can consist of more than one line, separated by (a literal) \n.

Constructors

Messages that are named ' new ' or that start with ' new( ' are special messages. They can be sent only once to objects that were declared with a '/' before their names. On receiving a 'new' message, the object will be created and its lifeline will become visible.

Destructors

Messages that are named ' destroy ' or that start with ' destroy( ' are also special. They can only be sent to an object that is not active. After receiving the destroy-message, the object may become active for the last time and, for example, send some destroy messages to other objects. But after this last activity ended, the object is destroyed (denoted by a cross below its lifeline) and cannot be reclaimed.

Actor messages

Actors can only send and receive asynchronous messages that return immediately. An asynchronous message will be generated that is sent back to the actor when the activity that was started by his message is finished.

If an actor sends a message to an ordinary object, all activities will be finished before. An actor should typically send the first message of the diagram, but this is not necessary, sequences without even a single actor are still supported.

Broadcast messages

See multithreading .

Annotations

Diagrams can be annotated in three different ways.

Source text comments

First, you may insert lines starting with a '#' in the textual description. These lines serve as comments and will not be interpreted, unless they start with '#!', which indicates an active comment.

Title

A line of the form

#![<title>]

specifies a diagram title. If it is present, the diagram will be surrounded by a frame, with the title written at the top left corner of the frame.

Description

A sequence of lines of the form

#!>>
#!A paragraph
#!of text describing
#!what is going on.
#!<<

is interpreted as text that will be written above the diagram.

Fragments

Second, a sequence of messages can be declared to be a fragment of the diagram. A fragment is represented by a frame surrounding those messages. It has a type (for example: alt, cond, or opt), appearing in the top-left corner, and a text, appearing in square brackets at the top of the frame. The text typically represents a condition. For example: 

[c:<type> <text>]
  foo:bar.message_1
  foo:bar.message_2
  ...
  foo:bar.message_n
[/c]

Fragments can be slightly abused: if you write [c <text>] (without the colon), all of the text will appear in the small box in the top left corner.

Fragments may contain sections. To open a new section, insert a line of the form

--some text

The effect is that a dashed line is drawn from the left to the right end of the current fragment frame, with "some text" being written below this line.

Notes

Third, there are notes. These appear in a box resembling a piece of paper that is arranged to the right of a lifeline. Notes are a part of the message section. The top of the box is where an arrow belonging to a message specified at the same position in the text would appear. The syntax is similar to a here-document delimited by an asterisk followed by a number (without the <<). 

*<num> <name>
multi-
line
note
*<num>

<name> is the name of the lifeline such that the note is to the right of it. <num> is the unique number identifying the note. You can refer to this number anywhere in the code - even before the note - in order to associate the note to messages or lifelines. For this you add one of the following prefixes to a message or the name of a lifeline:

Example: 

*5 foo
  foo calls bar's wait method
*5
*6 foo
  foo is waiting for bar
*6
*7 foo
  bar is ready
*7

(5,7)foo:ready=bar.wait()
(6)foo
  bar:do something
(6)foo
bar:do something more

If you use a "+" instead of a "*", the note box will consume as much vertical space as it needs and there will not be any message arrow or other note box beside it. When using "*", the note box will consume its own vertical space only if it is followed by a message arrow that is adjacent to one its both neighbour lifelines.

There are no direct associations between notes and objects. If one wishes to note something concerning an object or actor, she or he should specify a note belonging to the corresponding lifeline before any message has been specified.

Links

A single-lined note that starts with "link:" is interpreted as a link to another sequence diagram. The part of the line that follows is a URI (see RFC 3986 ) of an sd file. If the URI is relative, it is resolved against the location of the file of the current diagram. Example: 

#BEGIN of file "a.sd"
a:A

*1 a
link:b.sd
*1 a
#END
          
#BEGIN of file "b.sd",
#located in the same directory as "a.sd"
b:B
#END

When the note in the "a.sd" diagram is clicked, "b.sd" will be opened.

There is a problem when the characters behind "link:" contain spaces. This is a bad URI syntax. Spaces must be replaced by "%20". Especially on Windows, where directory names with spaces are far from being exceptional - for instance "Program Files" - one may easily run into this problem when trying to specify absolute paths.

Those characters are interpreted as a URI for the sake of platform independence. This means that even on the Windows platform, "/" is to be used as a separator in a path to a file. Absolute path names should start with "file:/".

Automatic completion

When you have entered a (non-empty) prefix of a name of an object, you can press the TAB key (like in a UNIX shell) or Ctrl-Shift-Space (like in some IDEs) for completing the name automatically or for browsing through (via successive keystrokes) all object names with that prefix.

If there is whitespace or a delimiter (one of {'>', ':', '='}) to the left of the cursor, the TAB key will behave normally, so you can still use it for indentations.

Automatic redrawing

By default, a new diagram is generated from your text almost as soon as the text changes, even if this change in text would leave the diagram unchanged.

This is a suitable behaviour for a standalone PC that is reasonably well equipped. In some situtations, however, especially when Quick Sequence Diagram Editor acts as a remote X client, it can be a nuisance. So you may disable automatic redrawing in the preferences dialog. When it is disabled, only a syntax/semantic check is performed. To see a new diagram, you must click "Redraw" or type F5.

The time that passes between a change of text and a redrawing or a syntax/semantic check can also be adjusted in the configuration dialog (see "Redraw/syntax check delay"). It may be desirable to have two different delays (one for redrawing, one for the check), but this feature is not (yet?) implemented.

Preferences

There are some types of preferences, which can all be adjusted in the tabs of a single preferences dialog.

Filtering

The contents of the text area can be replaced by the output of a command that you have entered after clicking the filter icon. If no text is selected, the whole of the text is used as the command's input and replaced by its output, otherwise the replacement is applied to the selection only.

The field where the command is entered can be left by clicking the ESC key. This may also terminate a command that has been entered and has not yet finished. There is a history of commands you have already entered in this session, through which you can browse using the cursor up and cursor down key.

This feature can be used by people who are too lazy to use the file dialog in order to load a file. For example: cat ~/my_diagram.sd. It can also be used for replacing patterns: sed s/foo/bar/g. Or to remove lines that contain comments: grep -v # ... Of course cat, sed and grep must be available on the system then.

RT diagram server

Diagram specifications can be transmitted through a TCP socket and displayed in real time, i. e. as soon as a new line is transmitted, the diagram will be updated.

To use this function, select "Start/stop RT server" in the Extras menu and enter a port number. A process that connects to the port will have to follow a very simple uni-directional protocol:

The server is started automatically if the "Autostart RT diagram server" flag is set to 1 in the configuration dialog.