Editing statecharts

Creating and deleting statecharts

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.

Creating a statechart

In order to create a new statechart, use the project explorer view:

1. Right-click on a project or on a folder you want to create the new statechart in. The context menu appears.
2. In the context menu, select New → Other…. The New dialog appears.
3. In the New dialog, select YAKINDU SCT → Statechart Model and click Next >. The New YAKINDU Statechart wizard appears.
4. In the File Name field, enter a filename for the statechart file to be created. The filename extension must be .sct.
5. Click Next >.
6. In the wizard, select a statechart domain. Which domains are available depend on your YAKINDU Statechart Tools license. The Default domain for „normal” statecharts without any language integration is always available.
7. Click Finish.
8. If the Confirm Perspective Switch dialog appears, answer its question as you see fit.
9. The new statechart file is created in the location you specified and opened in the statechart editor.

Copying an existing statechart

In order to copy an existing statechart file, proceed as follows:

1. In the project explorer view, right-click on the statechart’s filename. The context menu appears.
2. In the context menu, select Copy.
3. Right-click on the project or folder you want to insert the copied file in. The context menu appears.
4. In the context menu, select Paste.
5. If there is already a file with the same name as the file to be copied in the target project or folder – which is always the case if you are copying a file within the same project or directory –, the Name conflict dialog appears.
   1. Specify a name for the new file. The Name conflict dialog and makes a suggestion, which you can modify.
   2. Click OK to paste the new file to the target project or folder.
6. If the target project or folder does not contain a file with the same name as the source file, the copied file will have the same name as the original.

Deleting a statechart

In order to delete a statechart file, proceed as follows:

1. Right-click on the statechart file in the Project Explorer view. The context menu appears.
2. In the context menu, select Delete.
3. The Delete Resources confirmation dialog appears. You have three choices:
   1. Click Preview > to inspect what the delete operation is going to do, if confirmed.
   2. Click Cancel to cancel the delete operation. Your statechart file will persist.
   3. Click OK to actually delete the statechart file.

Editor UI

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 perspective

SC Modeling is an Eclipse perspective supporting the modeling of statecharts. The perspective defines the following views and their positions:

• Project Explorer (left): This view displays your workspace and projects, folders, and files contained therein. You can also use the Project Explorer to inspect the internal structure of your statechart models.
• Properties (bottom): This view displays properties, regarding the semantic model or the graphical appearance, of the selected element in the statechart editor. You can directly edit these properties in this view.
• Problems (bottom): This view displays errors and warnings existing in your workspace. Double-clicking on an entry typically opens the location of the respective error or warning.
• Tasks (bottom): This view displays any tasks you have defined in your statechart previously. Section "Working with statechart tasks" explains how to do that.
• Outline (right): This view is a bird’s eye view on the opened statechart. It also indicates the current viewport for better orientation in large models.

You can change the positions and sizes of these views, you can delete them, or add more views, using standard Eclipse mechanisms.

Canvas

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:

• Add or remove a region
  • To add a region to the canvas, select Region in the editor palette, then click on the canvas location you want to place the region.
  • To remove a region from the canvas, select the region, then
    • press the [Del] key, or
    • select Delete from model in the context menu, or
    • select Edit → Delete in the menu bar.
• Zooming
  • Press and hold [Ctrl] and turn the mouse wheel to zoom in or out.
  • Right-click on the canvas to open its context menu. In the context menu, several zooming functions are available in the Zoom submenu.

Editor palette

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

Editing action tools

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.

Statechart elements tools

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.

Outline view

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.

Graphical overview

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.

• Drag this rectangle with your mouse to move the statechart editor’s viewport.
• Click into the outline view to position the rectangle’s center to the point you have clicked.

Hierarchical outline

Click on the Outline icon in the Outline view’s title bar to engage the hierarchical outline.

Problems view

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.

Editing states and other nodes

Generally, there are two different ways to edit states and other nodes:

• Using the graphical editor to modify a node in the diagram.
• Selecting a node and editing its properties in the properties view.

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.

Editing transitions

Generally, there are two different ways to edit transitions:

• Using the graphical editor to modify a transition in the diagram.
• Selecting a transition and editing its properties in the properties view.

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.

Editing the documentation of states and transitions

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:

1. Right-click on the object.
2. In the context menu, select Toggle documentation.
3. The object now shows its documentation in place of the formerly displayed text.

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.

Editing regions

In a statechart model, you can have

• top-level regions, which are directly placed on the canvas, and
• regions inside of composite or orthogonal states.

Their graphical representation differ somewhat, thus editing them is also somewhat different.

Editing top-level regions

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.

Editing regions in orthogonal states

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:

1. Right-click on the orthogonal state’s title. The context menu opens.
2. In the context menu, select Toggle Subregion Alignment.
3. The layout of the regions switches from horizontal to vertical or vice versa.

Changing the name of a region

You can change the name of a region in the statechart editor as well as in the properties view.

• In the statechart editor,
  • double-click on the region’s current name,
  • edit the name in the text field that appeares after double-clicking,
  • press the [Return] key to finish editing.
• In the properties view,
  • modify the Region Name property. It is a region’s only property you can access through the properties view.

Editing hierarchies

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.

Using subdiagrams

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.

Refactorings

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.

Renaming variables, events and interfaces

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

• The Rename … dialog opens.
• In that dialog, type the entity’s new name into the text field.
• Click on OK to change each occurence of the old name to the new name.
• Click on Cancel to not rename anything.

Folding incoming actions

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.

Folding outgoing actions

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.

Unfolding entry actions

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.

Unfolding exit actions

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.

Grouping states into composite

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.

Extracting subdiagram

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.

Inlining subdiagram

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.

Using editing proposals

Using text proposals

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:

• Double-click on a proposal to insert it in the text at the current position.
• Use the up and down arrow keys to navigate to the proposal you want to insert in the text, then press [Return] to actually insert the proposal at the current position.

Using actions proposals on states

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:

• Double-click on a proposal to execute it.
• Use the up and down arrow keys to navigate to the proposal you want to execute, then press [Return] to actually execute it.

Comparing statecharts

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

Comparing a statechart to its local history

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:

1. In the project view, right-click on a statechart model file. The context menu opens.
2. In the context menu, select Compare With → Local History….
3. In the local history, double-click on the file’s version to compare to.
4. The comparison results are shown.

Comparing two statecharts

To compare two statecharts, proceed as follows:

1. In the project view, select two statechart model files.
2. Right-click on one of the selected statechart model files. The context menu opens.
3. In the context menu, select Compare With → Each Other.
4. The comparison results are shown.

Comparing three statecharts

To compare three statecharts, proceed as follows:

1. In the project view, select three statechart model files.
2. Right-click on one of the selected statechart model files. The context menu opens.
3. In the context menu, select Compare With → Each Other.
4. The Select common ancestor dialog appears. It shows the three selected statechart model files.
5. Select one of them. It will be regarded as the common ancestor of the two others.
6. The comparison results are shown.

Exporting a statechart as an image file

A complete statechart or parts of it can be saved as an image file as shown in the following steps:

• In the statechart editor:
  • To create an image file of the whole statechart with all regions and definition section, right-click on the q.
  • To create an image file of some statechart elements, select these elements and right-click on one of them. In the example below, the main region has been selected.
• The context menu appears.
  
• In the context menu, select File → Save As Image File....
• The Save As Image File dialog appears.
  
• Specify the filesystem folder for the exported image file in the Folder text field.
• Enter the name of the export image file into the File Name text field. The filename extension depends on the selected image format (see below).
• Select the image format from the Image Format drop-down menu. YAKINDU Statechart Tools supports the following formats:
  

  Image format	Description
  BMP, GIF, 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
  PDF	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.

• The Quality (%) text field is active for JPEG images only. JPEG is a lossy format, and reducing the quality results in a smaller file size. However, due to the nature of statechart images, a lossless format like PNG is most often a better choice, for sure in quality and perhaps even in file size.
• Check Overwrite existing file without warning if you don’t want to be bothered by a confirmation dialog which will appear if the export file already exists.
• Check Export to HTML to create both the image file plus an HTML file including it.

Working with statechart tasks

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.

Using the example wizard

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.

Downloading the examples repository

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.

1. In order to start the example wizard, select File → New → Example… in the YAKINDU Statechart Tools main menu. The New Example dialog opens.
2. In the New Example dialog, select YAKINDU Statechart Examples, then click on Next >. The example wizard opens.
3. The example wizard outputs a message saying that it could not find any examples and offers to download them.
4. Click on the Download button. The example wizard downloads the online examples repository and creates a clone of it on your local computer. This can take some time. – Downloading can fail for a variety of reasons, not being able to access the Github server being one of them. If this happens, don’t panic – and read how to manually create a local copy of the examples repository.

Example wizard when invoked for the first time

When the download is completed, you can browse the examples repository.

Changing the repository location

You can change the location used by the example wizard to store the online repository’s local clone.

1. When the example wizard shows the Download button on its first start, click on the link "change the storage location here". The example wizard’s preferences dialog opens. Alternatively, open Window → Preferences and select YAKINDU SCT → Example Wizard.
2. On the examples preferences page, enter the desired directory into the Storage Location text field.
3. Click on OK. The dialog closes.

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.

• If the directory exists, the example wizard searches it for examples and displays them.
• If the directory does not exist, the example wizard behaves as if being called for the first time. That is, it informs the user that it does not have any examples yet and offers to download them.

Browsing the examples repository

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

Manually creating a local copy of the examples repository

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

1. download the examples repository elsewhere, i. e. on a computer with Internet access,
2. copy it to the computer you want to run YAKINDU Statechart Tools, and
3. have the example wizard work with that local copy.

Subsequently we will explain the necessary steps in detail.

Downloading the repository as a ZIP archive:

1. On a computer with Internet access, go to the examples repository’s release branch.
2. Click on the green Clone or download button. A submenu opens.
3. In the submenu, click on Download ZIP.
4. The download starts and transfers the ZIP archive file examples-release.zip to your computer.
5. Copy the examples-release.zip file to the computer without Internet access and continue with the following steps on that machine.
6. Unpack the archive file. A directory named examples-release is created, containing the YAKINDU Statechart Tools examples repository.
7. In YAKINDU Statechart Tools, select Window → Preferences. The preferences dialog opens.
8. In the preferences dialog, navigate to YAKINDU SCT → Example Wizard.
9. Click on Browse..., and select the folder that you just extracted from the ZIP file, then click OK.
10. On the next try, the example wizard will now show a catalogue of YAKINDU Statechart Tools examples.

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.

1. Clone https://github.com/Yakindu/examples to your local computer. If you are using a command-line tool, the proper command to create the directory examples on your disk is:
   git clone 'https://github.com/Yakindu/examples.git'
2. Step into that directory:
   cd examples
3. Checkout the release branch:
   git checkout release
   Now the examples directory reflects the current release state.
4. In the YAKINDU Statechart Tools main menu, select File → New → Example…. The New Example dialog opens.
5. In the New Example dialog, select YAKINDU statechart examples and click on Next >. The example wizard opens.
6. When the example wizard is opened for the first time, there are no examples on the local disk yet.
7. In YAKINDU Statechart Tools, select Window → Preferences. The preferences dialog opens.
8. In the preferences dialog, navigate to YAKINDU SCT → Example Wizard.
9. Click on Browse..., and select the folder you just cloned, then click OK.
10. On the next try, the example wizard will show a catalogue of YAKINDU Statechart Tools examples.

Updating the examples repository

When 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

• Click on the Update button to update your local repository.

If your storage location is a plain directory and not a clone of the online examples repository, no update will ever be done.

Contributing your own examples

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.

Preferences

Many aspects of YAKINDU Statechart Tools can be configured by preferences. You can find them here:

1. In the main menu, select Window → Preferences. The Preferences dialog appears.
2. In the navigation on the left-hand side, scroll to YAKINDU SCT. Open it and its subentries as needed.
3. Click on an entry to display the associated preference pane on the right-hand side of the Preferences dialog, see e.g. figure Preferences: Diagram Appearance.

In the subsequent sections we will quickly walk through the preferences.

Diagram appearance

Preferences: Diagram Appearance

Colors and line styles

The diagram appearance preferences define default colors for the backgrounds and borders of states and regions, as well as the default routing style for transitions and other lines, with oblique and rectilinear being the options at your choice.

Please keep in mind that colors and line styles 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.

Showing transition priorities

In order to display transition 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.

Disabling live validation

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.

Example wizard

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.

Expressions preferences

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 pane these hidden dialogs will be shown again at their respective locations.

Expression syntax coloring

Preferences: Expression syntax coloring

This preferences pane defines foreground color, background color, font, and style for displaying certain syntactical elements in statechart language texts.

Expression templates

Preferences: Expression templates

Templates are sections of textual code that occur frequently enough that you would like to be able to insert them with a few keystrokes. 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 that begin with that character appear. Double-click on a template to insert it.

On this preference pane you can create, edit, and delete statechart language templates.

Generator model

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.

Generator model refactoring

Preferences: Generator model refactoring

Change these preference settings for refactoring in generator models as you see fit.

Generator model syntax coloring

Preferences: Generator model syntax coloring

This preferences pane defines foreground color, background color, font, and style for displaying certain syntactical elements in generator model texts.

Generator model templates

Preferences: Generator model templates

Templates are sections of textual code that occur frequently enough that you would like to be able to insert them with a few keystrokes. 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 that begin with that character appear. Double-click on a template to insert it.

On this preference pane you can create, edit, and delete generator model language templates.

Generator model filter

Preferences: Generator model filter

The IDE usually executes all generator models in current workspace. However, what might be inconvenient in some cases, especially if you have a lot of different generator models. To exercise a more fine-grained control of which generator models should be executed, it is possible to exclude or „filter away” particular generator models or entire folders from the automatic build execution.

Please note that this is a project-specific setting, which you won’t find via Window → Preferences. In order to create or modify a filter configuration, proceed as follows:

1. In the project explorer, right-click on a project name. The context menu opens.
2. In the context menu, select Properties. The Properties dialog opens.
3. In the menu on the left, select YAKINDU SCT → SGen Filter.
4. In the settings pane on the right, use the Add… and Remove buttons to maintain a list of generator models or folders that have to be ignored in automatic builds.
5. Click on OK to store and activate your modifications.

Simulation

Preferences: Simulation

Set your color preferences for the statechart simulator on this preference pane.