Searching and navigating in statecharts

Searching and navigating in statecharts Copy link to clipboard

itemis CREATE support you in quickly finding model elements and navigating to them.

The larger the model, the greater the need to quickly search for certain elements, e.g., for all states with a given name or name pattern, all occurrences of a certain variable, etc. itemis CREATE' searching functionality helps you master even large statecharts.

Searching via search dialog Copy link to clipboard

One option, and the most complex one, is to use the search dialog. You can open it using the [Ctrl+H] shortcut or by selecting Search → Search… in the main menu.

Doing so will open a dialog with several tabs, as shown in the following screenshot:

The tab you want to use is Statechart search.

Please note: If you cannot find this tab, you probably disabled it in the past by mistake. You can enable it again by clicking on the Customize… button and selecting Statechart Search, as shown by the following figure:

Switching to Statechart search will show you a clean and easy to understand dialog, which can be extended using the Show advanced settings check box for a more professional usage. The following subsection describes the possible settings.

User tip: Checking the Remember last used page option in the Customize dialog will help you to keep the focus on the Statechart Search tab for further search processes.

Search dialog settings Copy link to clipboard

The Statechart search dialog has several options to control your search.

The following table lists the various search options and explains what the search function does if the corresponding checkmark is set.

Setting	Description
Case sensitive	Differentiate between upper-case and lower-case letters in the search string. If this option is not checked, upper-case letters and their corresponding lower-case letters are regarded the same.
Regular expression	Interpret the search string as a regular expression. Please note that itemis CREATE supports Java regular expressions, as explained in the java.util.regex.Pattern class API documentation.
Search for states/regions	Include states and regions with matching names in the search result.
Search for declarations	Include matching declarations in the search result. Declarations are statechart language elements in the definition section, such as variables, events, operations, and named interfaces. The search function will find all occurrences of matching elements.
Search for properties	Include elements with matching properties in the search result. The following items are regarded as properties: Documentation of model elements Behavior of states, i.e., local actions, etc. Text of text elements and notes
Scope: workspace	Perform the search operation on all statecharts in the workspace.
Scope: selected resources	If a statechart editor has the focus, perform the search operation only on that statechart. If the Project explorer view has the focus, perform the search operation on all statecharts in the selected resources.

Search view Copy link to clipboard

After setting the search options as needed, run the search using the Search button. The search results will be shown in a view called Search.

We will demonstrate the search view using the light switch example from our five-minutes tutorial, using the following settings:

Setting	Value
Search string	O*
Case sensitive	✘
Regular expression	✘
Search for states/regions	✔
Search for declarations	✔
Search for properties	✔
Scope: Workspace	✔
Scope: Selected resource	✘

The search view consists of three main components and looks like the following screenshot.

Component	Functions
Searchbar text section	Displays the search string and the number of matches. The latter is updated while the search is running.
Toolbar section	See section "Toolbar section"
Result section	See section "Result section"

Toolbar section Copy link to clipboard

The toolbar section consists of ten buttons with the following functionalities:

Button	Action	Functionality
	Redo search	Executes the same search again on the possibly changed model.
	Cancel searching	Cancels a currently running search. The button is active only if a search run is being executed.
	History	Use this function to display the search history, to select a formerly-executed search (click on Redo search to actually execute it), or to clear the history.
	Pin search	Pins the results view. Future search results will be shown in a new search view, instead of rewriting the pinned search view.
	Collapse all	Collapses the search result tree and displays the root entries only.
	Expand all	Expands the search result tree and displays all search result entries.
	Search menu	Contains various search options.
	Minimize	Minimizes the search view and all its sibling views. A “restore” symbol is shown in a sidebar.
	Maximize	Maximizes the search view and all its sibling views to the full window size.
	Restore	Undoes the Maximize function. This button is shown only if the search view is maximized.

Result section Copy link to clipboard

The result section displays the matching statechart elements in a two-column, tree-based view.

The left-hand column, named Location, shows location and type of each match. Additionally, the whole path from the project down to the matching element is shown.
The right-hand column, named Matches shows the matches themselves. Intermediate path elements that are no matches but are displayed in the Location column don’t have a counterpart in the Matches column.

You can perform certain actions on the entries in the first column:

	Action	Function
	Click on the button	“closes” the node and collapses all child nodes.
	Click on the button	“Opens” the node and expands its immediate child nodes.
	Double-click on a matching element	Navigates to the matching element in the statechart editor, as long a it is not a descendant of an internal or interface element.
	Double-click on a non-matching path element	Closes an expanded node, opens a collapsed node.

Finding references Copy link to clipboard

Another realized search feature is to find references of model elements. You can perform this search on choosing Find references in the context menu of:

model elements in the editor
model elements in the project explorer
referenced object in syntax-checking editors inside statechart models like the definition section or the state behavior editor

This will search for usages of the same element in the local statechart and display them in the search view. Using this method can help you to save time searching for usages of variables, events and operations inside your statechart.

The next section introduces the differences between the first method and this method.

Differences between “Find references” and "Search dialog" Copy link to clipboard

As stated in the previous section, Find references is searching for the usages of the exact same model element as selected, whereas in the Search dialog, you have to enter a search string which will find all occurrences of model elements that match the search string.

Finding occurrences of model elements matching the search string makes it possible to search in different statecharts at the same time, while finding references of a model element is limited to the statechart defining that model element. Depending on your search goals, one method could be more suitable than the other.

To clarify the difference between these methods, different search operations were done using the same model. The used model can be taken from the following figure. It does not have any meaning and is only used for clarification purposes.

Search operation	Results
Find references on variable test in the default (unnamed) interface	Finds two matches: Entry action in the test state using the test variable Definition of the test variable in the unnamed interface
Find references on variable test in named interface first	Finds one match: Definition of the test variable in the named interface first
Find references on state test	Finds one match: The test state itself
Search Dialog with the same settings as in section "Search view" and "test" being the search string	Finds four matches: Entry action in the test state using the test variable Definition of the test variable in the unnamed interface Definition of the test variable in the named interface first The test state
Search Dialog with the same settings as in section "Search view" and "test" being the search string	Finds one match: Definition of the test variable in the named interface first
Search Dialog with almost the same settings as in section "Search view", but with Search for declarations deactivated and with "test" being the search string	Finds match: The test state
Search Dialog with almost the same settings as in section "Search view", but with Search for states/regions deactivated and with "test" being the search string	Finds three matches: Entry action in the test state using the test vwe should ariable Definition of the test variable in the unnamed interface Definition of the test variable in the named interface first

As can be seen in this case the search dialog has problems with searching references for the variable test in the unnamed interface.

Open model element Copy link to clipboard

Open model element is another kind of search method. It can be used to quickly navigate to states and regions. To access Open model element, use the [Ctrl+Shift+Q] shortcut or select Navigate → Open model element in the main menu.

By doing so, the dialog shown in the next screenshot will open.

The dialog consists of a single input element and two output elements / .

A search operation performed with Open model element is equivalent to "Searching via search dialog" with the following setting:

Setting	Value
Search string	same as in
Case sensitive	✘
Regular expression	✘
Search for States/Regions	✔
Search for Declarations	✘
Search for Properties	✘
Scope: Workspace	✘
Scope: Selected resource	✔

Differences between Open model element and Search dialog are subtle, but noticeable. The results will promptly appear in while typing your search string in . The hierarchy of a selected result is displayed in as a text instead of using a tree.

Navigating to a result can be done by double-clicking on the result. Or select the result and clicking on the OK button or hit the [Enter] key.

The Open model element dialog remembers any matching search results. On reopening the dialog, remembered model elements matching the new search string will be displayed above any newly-found elements. This makes it easier to navigate to them again at a later time.

Remembered elements can be removed from the history by selecting them and pressing the [Del] key or by right-clicking on a remembered element and choosing Remove from history in the context menu.

Table of contents