Statecharts are comprised in
statechart model files. The filename extension of these files is
.sct. Their internal format is
XML Metadata Interchange or
XMI, which is an XML language.
In order to create a new statechart, use the project explorer view:
In order to copy an existing statechart file, proceed as follows:
In order to delete a statechart file, proceed as follows:
YAKINDU Statechart Tools comes with a statechart editor. This section explains the statechart editor and how you can use it to graphically edit your statecharts.
SC Modeling is an Eclipse perspective supporting the modeling of statecharts. The perspective defines the following views and their positions:
You can change the positions and sizes of these views, you can delete them, or add more views, using standard Eclipse mechanisms.
The canvas is the statechart editor’s drawing area. When you create a new statechart model, the canvas comprises the definition section and a single region.
The following list gives an overview of what kind of actions you can perform on the canvas:
[Del] key, or
[Ctrl] and turn the mouse wheel to zoom in or out.
The editor palette provides you with a set of various actions and statechart editing tools. By default, the palette is located right of the canvas, but you can also drag it to the left.
You can hide the palette by clicking on the small triangle on the right-hand side in the palette’s title bar. Click on the triangle again to make the palette reappear.
Editor palette
Below its title bar, the palette contains a toolbar with the following editing action tools (from left to right):
| Symbol | Action | Description |
|
Select | Left-click at an object to select it. |
|
Zoom in | Left-click to zoom in. Press
[Shift] and left-click to zoom out. Drag to zoom to selection.
|
|
Zoom out | Left-click to zoom out. Press
[Shift] and left-click to zoom in.
|
|
Note | Create a note, a text or a note attachment. |
The palette comprises a couple of tools serving to add statechart elements to the diagram (from top to bottom):
| Symbol | Description |
|
Adds a transition. |
|
Adds a state. |
|
Adds a composite state. |
|
Adds an orthogonal state. |
|
Adds a region. |
|
Adds an entry point. |
|
Adds a shallow history state. |
|
Adds a deep history state. |
|
Adds a final state. |
|
Adds an exit point. |
|
Adds a choice. |
|
Adds a synchronization. |
The Outline view allows you to keep the big picture of your statechart model and navigate it easily. It displays the model outline either as a graphical overview or as a hierarchical outline.
Click on the Overview icon in the Outline view’s title bar to engage the graphical overview.
While the statechart editor window – due to zooming or the size of the whole statechart – might display a cutout only, the Outline view shows the whole diagram as an overview. It is scaled down as needed to completely fit into the available area.
A light-grey overlay rectangle represents the statechart editor’s viewport.
Click on the Outline icon in the Outline view’s title bar to engage the hierarchical outline.
The problems view by default lists all errors, warnings and other types of messages in all open projects.
The messages are grouped by message type, typically “error” or “warning”. Click on the show/hide symbol to open or close the respective message group’s contents.
Double-clicking on an entry in the problems view takes you directly to the resource or model element causing the problem.
You can configure the problems view in a multitude of ways, e.g., to group entries by different criteria, to sort them in a specific way, or to restrict them to certain projects. You can even define multiple problems views, each with different selection or display criteria.
To start configuring the problems view, click on the small triangle pointing downwards in the Problem view’s title bar. A drop-down menu will open and display the options that you have.
To configure the view click the small triangle pointing downwards in the view’s title bar. A drop-down menu opens and shows the options you have.
Please note: The problems view reflects the error/warning status of persisted statecharts only, i.e., statecharts that have been saved to the statechart file. If you create an error during editing, for example a new state that is not (yet) connected to any other state, the respective element will have an error marker on the canvas, however, it will not appear in the problems view, unless you have saved the statechart. The same holds true for resolved errors: An error will disappear from the problems view only after you saved the fixed error to the statechart file.
Generally, there are two different ways to edit states and other nodes:
There are certain properties that you can only edit with one of these methods. For example, to modify a state’s position or size, you have to use the statechart editor. To change a state’s transitions' priorities, you have to use the properties view.
Generally, there are two different ways to edit transitions:
There are certain properties that you can only edit with one of these methods. For example, to add guidance points to a transition’s arrow, you have to use the statechart editor. To change a transition’s arrow’s color, you have to use the properties view.
You can attach documentation to states and transitions. In this context, documentation is some text offering additional information to a human reader. In the model, it does not serve any functional purpose.
By default, a state’s rectangle shows the state’s behaviour, and a transition shows its expression alongside its arrow. You can instead display an objects’s documentation, i.e., the documentation of a state or transition:
In order to return back to the object’s normal view, select Toggle documentation again.
While the documentation is shown, you can modify it in the statechart editor. Double-click on the documentation text field to start editing it. Click outside the state or transition to quit editing.
The properties view of states and transition always shows both documentation and statechart language elements side by side in different compartments. This might be a more comfortable way of editing any of them.
In a statechart model, you can have
Their graphical representation differ somewhat, thus editing them is also somewhat different.
You can place a top-level region anywhere on the canvas, and you can change its size at will. To change the location or the size of a region, use the graphical editor. Drag the region to move it elsewhere. Use a selected region’s handles to resize it.
Regions inside an orthogonal or composite state are confined by their enclosing state. They are sized automatically, depending on their contents, and they are arranged either vertically or horizontally.
You can toggle between vertical and horizontally representation of regions in an orthogonal state as follows:
You can change the name of a region in the statechart editor as well as in the properties view.
[Return] key to finish editing.
Statecharts can get rather big and complex. Composite states are a way to reduce complexity and thus make statecharts easier to create, comprehend and maintain. A composite state comprises a state machine of its own within a region. The states belonging to such a nested state machine are called substates. Orthogonal states are a generalization of composite states, comprising two or more independent state machines in separate regions that are executed virtually concurrently.
A complementary way to mitigate the size of large statecharts are subdiagrams. A subdiagram externalizes the possibly large region(s) contained by a composite state into a subdiagram. In this case the composite state no longer displays its substates. Instead it is visualized very similarly to a regular state. The only difference is a small icon in its lower right corner, marking it as a composite state and giving access to its internal structure: the subdiagram. This way a composite state consumes much less space and gives the user the opportunity to better envision the overall picture. Section "Using subdiagrams" explains how to work with subdiagrams, how to create them and how to inline them again, if needed.
Composite states resp. subdiagrams can be nested to any depth.
The statechart editor provides various refactorings to support editing these hierarchies.
As a statechart grows, it may easily become too big to still give a comprehensive overview of the whole model. Subdiagrams come as a solution. Basically, you can “fold away” a composite state into a subdiagram.
Composite state
When the Extract Subdiagram refactoring is executed on a composite state, all containing regions are extracted into a separate diagram. The composite state no longer clutters the diagram with all its internal details, but instead appears almost like a normal state. The only difference is a small decorator icon in the lower-right corner of the state, indicating the existence of a subdiagram. When you hover over this decorator with the mouse cursor, you’ll see a small preview of the subdiagram’s content.
Extracting a subdiagram creates entry and exit points in the subdiagram as needed.
Subdiagram popup window
A click on the decorator opens the subdiagram in a separate editor tab. The breadcrumb at the top allows easy navigation throughout the hierachy levels.
Subdiagram editor
Using the inlining subdiagram refactoring, you can turn a subdiagram back into the composite state.
By default, a statechart’s definition section is positioned at the left-hand side of the canvas.
You can edit the definition section in two different modes: Legacy mode and the new pinnable mode. You can select your preferred editing mode in the YAKINDU SCT preferences.
Legacy mode is the definition section’s traditional editing mode, which has been available in YAKINDU Statechart Tools for a long time already. Currently it is the default editing mode. However, a future version will make the pinnable mode the default.
To edit the definition section, double-click into it and enter your statements. While editing, syntax highlighting is applied to the text in the definition section. To quit editing, click outside the definition section. Now the text will appear without any syntax coloring.
Technically, the defintion section is part of the canvas. If you print the canvas or save it to an image file, the definition section is included in the result. Definition section and top-level region are always scrolled in sync, which might have the rather unwanted effect that your statechart diagram is scrolled off your screen if you have a very long definition section and you are editing something down below in it.
Pinnable mode is an improved editing mode that has been introduced with YAKINDU Statechart Tools 3.20. However, it is slightly incompatible with previous versions, so you have the choice to use it or not.
In pinnable mode, the definition section can be either part of the
canvas (“inlined”) or not (“pinned”), and you can change that at will. The definition section comes with a little pin symbol
at its top-left. Click on it, and the definition section will be detached from the canvas. This has a couple of advantages:
Collapsing the pinned definition section
Expanding the pinned definition section
By default, the pinned definition section takes 20 percent of the canvas' view, but you can resize it as you like.
You can unpin the definition section and inline it with the canvas. To do so, click on the pin symbol
, which in the pinned state is in the definition section’s upper-right corner.
Please note: Inlining the definition section is possible in the top-level diagram. If you are editing a subdiagram in pinned mode, the pin symbol is greyed out.
Please also note: Pinning and inlining the definition section changes your statechart model. You have to save it in order to maintain the current status.
Pinning the statechart diagram definition section
Inlining the statechart diagram definition section
In the pinned definition section, you can edit the name of the statechart by changing the displayed text in the top-center of the section.
Changing the statechart name
Choose the definition section editing mode to be used by setting the corresponding option in the preferences:
Refactoring means modifying certain model aspects while maintaining the model’s semantics. The statechart editor allows for the refactoring of variables, events, interfaces, and states, including composite and orthogonal states. A state’s context menu contains the Refactor submenu with the individual refactoring actions explained below. Depending on certain conditions, a refactoring might be executable or not, which will be explained below.
Using the Rename refactoring, you can change the name of a variable, event or interface throughout your statechart model. Each occurrence of that name will be changed to the new name.
To initiate renaming, right-click on the name of a variable, event or interface in the diagram editor, in the definition section, or in a text field in the properties view, then select Rename ….
Renaming a variable
When building a statechart model step by step, you may come into a situation where you have defined several transitions having the same target state and sharing a common set of actions.
The Fold Incoming Actions refactoring moves these actions from the transitions to the target state’s entry block. To preserve model semantics, only actions that are defined on all incoming transitions will be moved. Since the execution order must be preserved, the refactoring algorithm starts with the right-most action and proceeds action by action to the left. As soon as it detects an action that is not defined on all incoming transitions, it stops moving actions to the entry block.
Consider the following model:
Moving incoming actions to entry block
Only the most-right action y += 42 can be moved to the entry block of the target state. Although x += 1 is also a common action of both transitions, it cannot be moved to the target state, because the semantics of the B → Target transition would change, in that y = x would be executed before x had been incremented.
Another aspect to take into account are transitions leading to target states that are nested in composite states. Consider the following example:
Moving incoming actions into a nested state’s entry block
The actions y = x of the two incoming transitions leading to the Target state cannot be moved to Target's entry block, because doing so would change the model’s semantics. The reason is the composite state’s entry action x += 1. It will be executed after the action of transition A → Target and before the actions in the entry block of Target. Moving y = x from the transition to Target's entry block would change that order. The statechart editor pays regard to this constraint and prohibits the refactoring.
To fold incoming actions, right-click on the state to refactor, then select Refactor → Fold Incoming Actions in the context menu. The menu entry is active only if there are actual actions to move into the target state’s entry block, with the above rules applied.
The fold outgoing actions refactoring is similar to folding incoming actions, except that it moves actions from outgoing transitions to the source state’s exit block. To preserve model semantics, only actions that are defined on all outgoing transitions will be moved. Since the execution order must be preserved, the refactoring algorithm starts with the left-most action and proceeds action by action to the right. As soon as it detects an action that is not defined on all outgoing transitions, it stops moving actions to the exit block.
Preconditions for this refactoring are analog to "Folding incoming actions". Consider the following example:
Moving outgoing actions to exit block
Here, the actions y = x cannot be moved from the outgoing transitions to the exit block of the source state, because the composite state has an exit action. For the Source → A transition, the proper execution order is to first execute x += 1 of the nesting composite state’s exit block, followed by y = x of the transition. Moving y = x to the exit block of state Source would reverse this order and thus will be prohibited by the statechart editor.
To fold outgoing actions, right-click on the state to refactor, then select Refactor → Fold Outgoing Actions in the context menu. The menu entry is active only if there are actual actions to move into the source state’s exit block, with the above rules applied.
This refactoring is the reverse of folding incoming actions. It removes all entry actions from a target state and appends them to each of its incoming transition’s actions.
Transitions crossing the borders of composite states enclosing the target state might inhibit refactoring, see section "Unfolding exit actions" for an analogous example.
To unfold entry actions, right-click on the state to refactor, then select Refactor → Unfold Entry Actions in the context menu. The menu entry is active only if there are actual actions in the state’s entry block that can be moved to the state’s incoming transitions while maintaining semantic equivalence and preserving execution order.
This refactoring is the reverse of folding outgoing actions. It moves all exit actions from a source state and prepends them to each of its outgoing transition’s actions.
Transitions crossing the borders of composite states enclosing the source state might inhibit refactoring. Consider the following example:
Unfolding exit actions to outgoing transitions
Unfolding the exit action y = x of the Source state to the two outgoing transitions would be invalid, because the execution order of said action and the composite state’s exit action would be reversed.
To unfold exit actions, right-click on the state to refactor, then select Refactor → Unfold Exit Actions in the context menu. The menu entry is active only if there are actual actions in the state’s exit block that can be moved to the state’s outgoing transitions, while maintaining semantic equivalence and preserving execution order.
This refactoring creates a new composite state containing the selected states. The latter must belong to the same region.
To execute this refactoring, select one or more states from the same region, right-click on one of them, and select Refactor → Group States Into Composite in the context menu. The menu entry is active only if the selected states belong to the same region.
This refactoring extracts the regions of the selected composite or orthogonal state into a subdiagram. Entry and exit points are created as needed in the subdiagram. See section "Using subdiagrams" for more details.
To extract a subdiagram, right-click on the composite or orthogonal state to refactor, then select Refactor → Extract Subdiagram in the context menu.
This refactoring inlines the selected node’s subdiagram in order to show it directly in the composite state’s diagram region. See section "Using subdiagrams" for more details.
To inline a subdiagram, right-click on a composite state with a subdiagram, then select Refactor → Inline Subdiagram in the context menu.
Proposals assist you when writing statechart language expressions. Whenever editing some text anywhere in the graphical statechart editor or in the properties view, at any point you can press the
[Ctrl+Space] key combination to get some context-sensitive help.
Certain proposals, like statechart language keywords, have documentation associated with them. When such a proposal is selected, either using the mouse or the keyboard, this information is shown in a secondary popup window next to the proposal.
You can either use the mouse or the keyboard to select and insert a proposal in the text:
[Return] to actually insert the proposal at the current position.
When a state is selected,
[Ctrl+Space] opens a popup window showing a context-sensitive menu with possible action choices to perform on the state.
These action proposals have additional information associated to them. When a proposal is selected either using the mouse or the keyboard, this information is shown in a secondary popup window next to the proposal.
You can either use the mouse or the keyboard to execute a proposal:
[Return] to actually execute it.
The statechart editor allows for comparing two or even three statecharts to each other, displaying the results, and possibly merging selected differences. Figure "Comparing two statecharts" shows a sample comparison result.
Comparing two statecharts
Whenever a statechart is saved to its statechart file, the previous version of the file is saved to the local history.
Warning: The local history typically contains a few recent versions of a file. However, you should never rely on anything being available in the local history at all. It is definitely no replacement for a data backup or a version control system
To compare a statechart to an older version in the local history, proceed as follows:
To compare two statecharts, proceed as follows:
To compare three statecharts, proceed as follows:
A complete statechart or parts of it can be saved as an image file as shown in the following steps:
| Image format | Description |
|---|---|
| BMP, PNG | Lossless pixel image formats |
| JPG, JPEG | Lossy pixel image format. You can specify the image quality via the Quality (%) setting. |
| SVG | Scalable Vector Graphics |
| Portable Document Format |
Note
The image export functionality is subject to the capabilities of your Java Runtime Environment (JRE). You can export images only in those image formats your JRE actually supports.
While you are busily developing a statechart, it is quite common that you have ideas about what else you could or should do to improve the statechart. However, in order to not get side-tracked, you decide to do it later. Examples are to write a proper documentation for a state, to refine a transition whose final specification you don’t have yet, etc.
For all these and other purposes you can define
tasks in all places in your statechart where a comment is allowed. A task is a special comment comprising the words
FIXME or
TODO. Adding one of these words to a comment is called “tagging” the comment as a task.
The nice thing is that you don’t have to remember all the places you took a note and defined a task. YAKINDU Statechart Tools lists all of your tasks in the tasks view. Figure "Tasks defined by tags in the statechart showing up in the tasks view" is showing an example with various tasks being defined in a transition, in a state’s behavior, in a state’s documentation, and in the statecharts definition section.
Tasks defined by tags in the statechart showing up in the tasks view
In the example, state B has been selected in the statechart editor (top), so that the tasks defined in the state’s behavior and in its documentation are shown in the properties view (middle).
Task have a priority. While
TODO stamps a task as being of normal priority,
FIXME indicates a high-priority task.
By default, tasks are ordered by priority in the tasks view (bottom), and high-priority tasks are accentuated by a red exclamation mark. However, you can change the sorting order and other settings using the view’s menu. Click on the little triangle on the right-hand side of the task view’s title to open the view menu.
Double-clicking on a task in the tasks view navigates to the location where the task is defined. If needed, the corresponding statechart diagram is opened. The graphical element holding the task definition is highlighted.
Note
The tasks view is updated only when the statechart is saved.
The example wizard gives you convenient access to the examples in the public YAKINDU Statechart Tools examples repository. You can browse the available examples and read their documentation in the wizard. By a simple click you can instantiate an example as a new Eclipse project. Within such a sample project, you can explore and modify the state machine models using the statechart editor, run the state machines in the simulator, generate source code, etc.
Upon its first invocation, the example wizard downloads the complete examples repository and creates a copy on your local disk. After that, all examples are immediately available to you, even if you are offline. The example wizard will take notice when new examples are available in the online repository and offers to download them. It is also possible to download the examples repository out-of-band and later tell the example wizard where it can find the local copy.
When you start the example wizard for the first time, it does not yet have any examples available that it could show to you. Thus downloading the online examples repository is required as a special first step.
Example wizard when invoked for the first time
When the download is completed, you can browse the examples repository.
You can change the location used by the example wizard to store the online repository’s local clone.
You can change the storage location of your local examples repository clone at any time. In fact, it doesn’t even need to be a clone of the official examples repository. Any directory containing subdirectories with YAKINDU Statechart Tools examples suffices.
The example wizard shows the available examples on the left-hand side.
Click on an example to select it and show its documentation on the right-hand side.
Click on Finish to create the selected example as a new project in your workspace.
Example wizard showing all available examples
The example wizard tries to download a copy of the YAKINDU Statechart Tools examples repository and install it on your local machine. However, if your Internet access is restricted or you don’t have Internet access at all, this will fail.
To circumvent this problem, you can
Subsequently we will explain the necessary steps in detail.
Downloading the repository as a ZIP archive:
Alternatively, you can clone the repository. Cloning the examples repository containing the YAKINDU Statechart Tools examples is more complex than just downloading a ZIP archive. However, you will get certain advantages in return, like the ability to detect and receive updates, the option to create your own examples and submit them as a pull request, or to get hold of the complete history of the examples repository – which could also be considered a drawback, taking its size into account.
git clone 'https://github.com/Yakindu/examples.git'
cd examples
git checkout releaseWhen the example wizard is started and the storage location is a clone of the online examples directory, it checks whether there are any updates in the online examples repository. If new examples are available or existing examples have changed in the online repository, the example wizard offers to update your local examples repository clone accordingly.
Example wizard offering to update the examples repository
If your storage location is a plain directory and not a clone of the online examples repository, no update will ever be done.
If you have a project that you want to share with the community, you can contribute it as an example. Once the YAKINDU team has reviewed and applied your contribution, it will be available for all users of YAKINDU Statechart Tools via the example wizard’s update functionality.
For more information on how to contribute examples, please visit our Wiki page.
Many aspects of YAKINDU Statechart Tools can be configured by preferences. You can find them here:
In the subsequent sections we will quickly walk through the preferences.
Preferences: Diagram appearance
The diagram appearance preferences define
Please keep in mind that these settings will apply to new elements only. Existing regions, states, etc. will remain as they are. However, you can modify the properties of an existing element anytime, using its properties view.
By default, YAKINDU Statechart Tools highlights textual statechart language elements in different colors while the corresponding text fragment is being edited.
If the "Enable syntax coloring" option is checked, syntax highlighting is turned on all the time, i.e., also for text that is not being edited.
You can configure the colors to actually use on the following preference pages:
Check or uncheck the "Enable pinning of statechart definition section pinning" option to toggle between pinning and legacy mode of the definition section. Section "Using the definition section" explains what this is all about.
In order to display transition and region priorities in a statechart, set a check mark at the respective preference option. Section "Transition priorities" explains what transition priorities are and shows an example.
While you are editing a statechart, the statechart editor validates your model on each and every modification you make. That’s very helpful, because the editor provides you with instant feedback, so you can see immediately what is right, wrong, or dubious, and you can take corrective action, if needed.
However, on very large and complex statechart models, validation may take a considerable amount of time, causing delays and impeding your editing. Remove the check mark from Enable live validation, and your model will be validated only before it is saved to the statechart file.
Preferences: Example wizard
You can change the example wizard storage location here. This is a local directory where the example wizard stores your local clone of the examples Git repository. The default is the sct_examples directory in your home directory.
You could also change the location of the Git repository and the branch to use, but you won’t probably want to do that.
Preferences: Expressions
Certain dialogs in the statechart editor allow you to opt for never seeing them again. By clicking on the Clear button on this preference page the hidden dialogs pertaining to the statechart language will be shown again at their respective locations.
Preferences: Expression syntax coloring
This preference page defines foreground color, background color, font, and style for displaying certain syntactical elements in statechart language texts.
Preferences: Expression templates
Templates are sections of textual code that occur frequently enough to make you want to insert them with a few keystrokes only. This function is known as content assist; the sections of code that are inserted are known as templates.
To insert an existing content assist template, type the initial character, then press
[Ctrl+Space]. The templates whose names begin with that character will appear. Double-click on a template to insert it.
On this preference page you can create, edit, and delete statechart language templates.
Preferences: Generator model
By default, code generators automatically generate artifacts defined by generator models in .sgen files. Using this preference setting, you can switch this behavior off or on.
Preferences: Generator model refactoring
Change these preference settings for refactoring in generator models as you see fit.
The "Save all modified resources automatically prior to refactoring" option is somewhat dangerous, because you might have made changes to files that you intentionally do not want to save to disk – or at least not yet. For that reason, this option is turned off by default.
The
"Rename in editor without dialog if possible" pertains to how the renaming operation is performed. By default, if you click on a name and press
[Shift+Alt+R], you can edit the name directly in the source code, and all other occurences of that element are renamed while you are typing. If this is not possible or if this option is not checked, a dialog will ask you for the element’s new name.
Preferences: Generator model syntax coloring
This preference page defines foreground color, background color, font, and style for displaying certain syntactical elements in generator model texts.
Preferences: Generator model templates
Templates are sections of textual code that occur frequently enough to make you want to insert them with a few keystrokes only. This function is known as content assist; the sections of code that are inserted are known as templates.
To insert an existing content assist template, type the initial character, then press
[Ctrl+Space]. The templates whose names begin with that character will appear. Double-click on a template to insert it.
On this preference page you can create, edit, and delete generator model language templates.
Preferences: SCTUnit
Certain dialogs in SCTUnit allow you to opt for never seeing them again. By clicking on the Clear button on this preference page the hidden dialogs pertaining to SCTUnit will be shown again at their respective locations.
Preferences: SCTUnit refactoring
Change these preference settings for refactoring in SCTUnit source files as you see fit.
The "Save all modified resources automatically prior to refactoring" option is somewhat dangerous, because you might have made changes to files that you intentionally do not want to save to disk – or at least not yet. For that reason, this option is turned off by default.
The
"Rename in editor without dialog if possible" pertains to how the renaming operation is performed. By default, if you click on a name and press
[Shift+Alt+R], you can edit the name directly in the source code, and all other occurences of that element are renamed while you are typing. If this is not possible or if this option is not checked, a dialog will ask you for the element’s new name.
Preferences: SCTUnit syntax coloring
This preference page defines foreground color, background color, font, and style for displaying certain syntactical elements in SCTUnit source texts.
Preferences: SCTUnit templates
Templates are sections of textual code that occur frequently enough to make you want to insert them with a few keystrokes only. This function is known as content assist; the sections of code that are inserted are known as templates.
To insert an existing content assist template, type the initial character, then press
[Ctrl+Space]. The templates whose names begin with that character will appear. Double-click on a template to insert it.
On this preference page you can create, edit, and delete SCTUnit language templates.
Preferences: Simulation
Set your color preferences for the statechart simulator on this preference page.