rsouth / sequencer

Sequence diagram generator with simple text based grammar, to make it quick and easy to share ideas and document your system. Copy to clipboard for sharing on chat, or export as .PNG.

sequencer is a simple diagramming tool to make it easy for developers to share ideas

Highlights • Get Started • Demo • Themes • Download • Contributing • Credits • License

✅ What is sequencer?

Sequencer allows you to create simple and clear sequence diagrams, based on a simple grammar. Your diagram is drawn in real-time as you type, and is designed to be:

• easy to edit
• easy to share
• easy to version control

Sequencer is free and open-source, distributed as a single .exe (no installer), and has just the features you need to share and document your idea quickly.

🎥 Demo

⚡ Simple to get started

💬 Describe your sequence

Client -> Server: Request
Server -> Server: Parses request
Server -> Service: Query
Service -> Server: Data
Server -> Client: Response

💥 Your diagram is ready to go

• paste right in to chat, email, your wiki page
• export as a .png file
• share the source, or better yet - version control it!

See the Grammar page on the wiki for details of the current grammar.

🎨 Themes

Support for basic themes is progressing, the "Sketchy" theme is available since v0.0.3-pre-alpha.

Theme information can be found on the Themes wiki page.

🔨 Building

qmake
nmake release

https://github.com/rsouth/sequencer/wiki/Building

🚀 Download

Releases Page

Latest

Please download the latest release.

v0.0.3 pre-alpha 🍒

• Significant refactoring of rendering
• Added 'Sketchy' theme

v0.0.2 pre-alpha

• Rendering is now done in Qt QPainter on a QPixmap rather than using CImg
• More functional UI
  • Dirty checks before New, Open
  • Create New button works
  • Undo/redo functionality in text editor
• Code review items since last release
• Rendering changes:
  • Default font sizes are now smaller
  • Smaller arrow-heads
  • Rounded boxes around participant headers

v0.0.1 pre-alpha

• Grammar parity with jSequencer
  • Participants and messages
  • Synchronous and asynchronous messages
  • Self-referential messages
  • Reply messages
  • Header information (title, author, date)
• Qt UI implementation
• Sharing options (clipboard, .png export)

👍 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

🙏 Credits / Attributions

🖼️ Icons

Toolbar icons made by Dave Gandy from www.flaticon.com.

💡 Inspiration

WebSequenceDiagrams which is an online text-based sequence diagram generator with a commercial offering.

Sequencer is a C++ re-write of my own project jSequencer.

📘 License

This project is licensed under the terms of the GNU General Public License v3.0.

sequencer's Issues

Participant tokens should be coloured the same way

• consider the palette in terms of being visible (no yellow?) but also need a large enough pool of colours..
• look at palettes to avoid colours which don't work w/ colour blindness

Add actions inline as 'interactions'

See screenshot taken from https://developer.okta.com/blog/2018/09/27/test-your-github-repositories-with-docker-in-five-minutes

An alternative to self-referential interactions?

Label positions

Label positions are off vs those in jSequencer

C++

Java

Also see if we can have transparent background for labels rather than solid white.

Font sizes - default is too large

Cimg fonts are only 'good' at 13, 23, 53 etc - perhaps need to review fonts in CImg.

Found messages

Message from outside of the system.

=> Client :Request

Will render a filled circle with an interaction to the Client.

Perhaps we can have an equivelant for messages leaving the system?

Client => :Response

Or does it need to be directional? i.e. a repsonse to the entry system vs a message ongoing to the next part of the process

Client <=: Response

Client =>: Response

Colour invalid lines in red

Colour invalid lines in red

• don't evaluate until the line is 'complete' i.e. the cursor is no longer on the line
• "messages" box or floating window to show these issues - line numbers are useful here, see #53

alterntively status bar could say "Error line 4: Unknown participant 'Srever'"

Triage & Organise Imported Issues

Issues imported from jSequencer and old Sequencer++ project may not apply or may be incorrectly specified for Sequencer - all need to be reviewed and prioritised or closed out as necessary.

Save preferences

2 things:
Save preferences to file, read on startup.
No file should exist to begin with, it's just saved to store state of the app .
If fail to save, ignore (maybe app is being run from inside a zip.

Properties:

• window location
• currently open file

http://commons.apache.org/proper/commons-configuration/

2 - put the filename of the currently open file in the tab title.
Put a star on the title when the state is dirty.
Add a close button to the tab to close the current document.
No file means 'untitled'.

Line numbering

This might be useful e.g. in chat, "line 14 the message should be 'data' not 'reply'"

Interaction message should be highlighted

Interaction message should be either a different colour / italic etc.

Perhaps allow some user configuration wrt the style.

Investigate macOS Support

• qt itself should be OK but would need to be re-built
• there is some windows specific code in Sequencer.
• is there anywhere 'renting' build time on macOS hosts?

Icons

Icons from https://www.flaticon.com/packs/font-awesome
Downloaded as 110912-font-awesome

Attribution should be done as

Icons made by Dave Gandy from www.flaticon.com

<div>Icons made by <a href="https://www.flaticon.com/authors/dave-gandy" title="Dave Gandy">Dave Gandy</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div>

• add to readme
• add to about window

Implement 'export as image'

sync vs async messages

Solid arrow heads represent synchronous calls, open arrow heads represent asynchronous messages

in jsequencer the syntax for the async call (open head) is >>
e.g.

Server ->> Service: Async query

or simple > for syncronous

Server -> Service: Blocking query

'About' dialog HTML is too small

Looks fine on hi-dpi screen, too small otherwise.

Participant Colours

Metadata grammar

:color Client blue ?
:color Server #f00

Replace CImg with stable 2.9.1 version

Version label

Far-right of the toolbar, add "v1.2.3" label which can switch to 'update available' highlighted green when a new version is available to download.

Headless mode

Something like

sequencer.jar -in source-file.seq -out my-diagram.png

or in future

sequencer.jar -in source-file.seq -out my-diagram.png -theme sketchy -width 1000

I was thinking if the diagram source is version controlled, the build system could generate the diagrams on each build/release etc, and publish them as artefacts. This could mean the diagram on a wiki (or wherever) is always up to date.

Add license header to all (Sequencer) h/cpp files

Copyright (C) 2020 rsouth (https://github.com/rsouth)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Logging

Log to a file when running in debug mode.
Or when started with -enable-logging flag (could have a checkbox in Help menu to enable this also)

Stream of consciousness part - add a floating tool window to show the log in-app..

Icon

Windows 'metadata' App name / version etc

Interaction type hints

When hovering on an interaction token (-> etc) tooltip should help with a message like "sends message to" or "sends async message to", "sends reply to"

Or potentially this could be in the status bar for the selected line

'reply' messages

represented by a dashed line

Server -> Client
Client --> Server

New File button

Debug rendering

Use NDEBUG flag to fill background grey and draw diagram border in DEBUG build.

 #ifdef NDEBUG
  // nondebug
 #else
  // debug code
 #endif

Enable / Disable Buttons Based on Document State

track document state

• if document is empty, the to-clipboard and to-png options should be disabled
• if document state is not dirty, save should be disabled (save-as always enabled)
• dirty checks when opening a file or opening the example content

Minor rendering refinements

• arrowheads are too large
• ...

Allow click & drag to scroll around the document

Unit tests

commit the original googtest suite and expand on them

Cursor relocates to start of file when using 'add metadata' buttons

when using 'add title'/author/date buttons the cursor position is relocated to the start of the file

Variable width lanes

Fixed width lanes are too inflexible.

Make them variable based on the participant name length (potentially length of longest message?)
Maybe still impose a max width, and look at changing the font size / wrapping messages.

String width on left-facing msg incorrectly incorporated in to diagram width calc

The width of a string going from R->L is incorrectly calculated in to the diagram width.

Participant tokens should be highlighted when selected

When a participant token is selected, all instances of that same participant should be

• highlighted (box around? coloured?)

GUI Themes - Light / Dark

Light / Dark GUI Themes

Set up Sonar

https://github.com/marketplace/actions/sonarcloud-scan

also take a look at https://github.com/marketplace/codefactor

Round off boxes (optionally?)

Participant boxes are round by default; maybe that should be set as the start of basic 'themes' instead

Also optionally (theme?) round the lines of self-ref interactions.

Just about improving appearance.

Diagram theme support

Big job.

Support for themes, via a grammar
:theme default
:theme sketchy
...etc

Selectable via a drop-down in the GUI (which adds the grammar).

Would each renderable need to support this or can it be exeternalised such that a renderable still 'draws' the start/end points but the Graphics draws in the given style?

'Save As' icon

Maybe the same 'disk' as Save, but with a pen on it ?

Update demo recording

Demo recording on readme is still from jSeq, replace it with a new one from Sequencer.

Implement 'copy to clipboard'

Highlight relevant lanes when editing a line

thoughts on this

• draw a box around the lane(s) involved in the interaction?
• draw those lanes in a different colour?

Exception handling

A number of exceptions are thrown in parsing, caught but left unhandled.

make a 'parsingexception' and throw with reason/line number for logging / gui display.

Prevent re-rendering unchanged diagram

delta check between current document and previous render; stop wasteful re-rendering

About dialog

Link to gitub repo
Icon attributions
Leave it open to add more notes / links

Dirty checks on the document

Prompt to save before replacing content

• quit,
• open,
• example file

post-0.0.1 code review

Review the state so far, raise tickets and prioritise.

Mostly looking for

• C++ issues, would like to learn more about C++14/17 features
• Repetition (e.g. the string join which was moved to StringUtils)
• encapsulation issues - sequencer.cpp is pretty heavy
• commit the old set of unit tests and bring them up to date #66
• efficiency; lots of places where unnecessary copies are happening for example
• caught exceptions which aren't handled #67
• unused old vars/methods
• StringUtils::get_token_value isn't really re-usable, and had to re-read it's usage to understand
• StringUtils::replace can return nullptr; don't think that's good?
• RenderingUtils caching could use a re-working...

update; struck out issues to be ticketed seperately

Add Title / Author / Date GUI buttons

Multiple (tabbed) diagrams

Allow multiple diagrams open at once with the tabbed interface.

The tabs should move to contain both the text area and the canvas (currently only contains the textarea).