|
|
@@ -0,0 +1,188 @@
|
|
|
+
|
|
|
+h1(#search_and_nav_searching_and_navigating_in_statecharts). Searching and navigating in statecharts
|
|
|
+
|
|
|
+The larger the model, the greater the need to quickly search for elements, for example, all states with a given name resp. name pattern, all occurrences of a certain variable, etc. This section explains how _YAKINDU Statechart Tools_ supports you in finding model elements and quickly navigating to them.
|
|
|
+
|
|
|
+###. FIXME (RKL): Describe how to find transitions!
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h2(#search_and_nav_searching_via_search_dialog). Searching via search dialog
|
|
|
+
|
|
|
+One option, and the most complex one, is to use the search dialog. You can open the dialog using the shortcut @[Ctrl+H]@ or through selecting _Search → Search..._ in the main menu.
|
|
|
+Doing this will open a dialog with several tabs as shown in the following screenshot:<br/>!images/search_and_nav_search_dialog.png(Search Dialog)!
|
|
|
+
|
|
|
+The tab you want to use is _Statechart Search_. If you can not find this tab, you probably disabled this in the past by mistake. You can enable it again by pressing the _Customize..._ button and selecting _Statechart Search_ as you can see on the following figure:
|
|
|
+!images/search_and_nav_customize_dialog.png(Customize Dialog)!
|
|
|
+
|
|
|
+
|
|
|
+Switching to _Statechart Search_ will show you a clean and easily understandable dialog, which can be extended using the _Show advanced settings_ check box for a more professional usage. The possible settings will be described in the following subsection.
|
|
|
+
|
|
|
+bq.. *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.
|
|
|
+
|
|
|
+
|
|
|
+h3(#search_and_nav_search_dialog_settings). Search dialog settings
|
|
|
+
|
|
|
+The _Statechart Search_ dialog has several options to control your search.
|
|
|
+
|
|
|
+!images/search_and_nav_model_search_dialog_extended.png(Advanced Search Dialog)!
|
|
|
+
|
|
|
+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":https://en.wikipedia.org/wiki/Regular_expression. Please note that YAKINDU Statechart Tools supports Java regular expressions, as explained in the "java.util.regex.Pattern class API documentation":https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html. |
|
|
|
+| _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: <ul><li>_Documentation_ of model elements</li><li>_Behavior_ of states, i.e., local actions, etc.</li><li>_Text_ of text elements and notes !(inlinemediaobject)images/docu_editor_palette_070_symbol_note.png(editor palette symbol "Note")!</li></ul> |
|
|
|
+| _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. |
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h2(#search_and_nav_search_view). Search view
|
|
|
+
|
|
|
+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":../tutorials/tutorials.html#tutorial_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_ | ✘ |
|
|
|
+
|
|
|
+###. FIXME: Don't use an "O" in the example, because of danger of confusion with a "0".
|
|
|
+
|
|
|
+###. FIXME: A screenshot would be better than a table.
|
|
|
+
|
|
|
+The search view consists of three main components and looks like the following screenshot.
|
|
|
+
|
|
|
+!(full)images/search_and_nav_result_view.png(Search view)!
|
|
|
+
|
|
|
+|_. Component |_. Functions |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_number_1.png(Searchbar text section)! Searchbar text section | Displays the search string and the number of matches. The latter is updated while the search is running. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_number_2.png(Toolbar section)! Toolbar section| See section ""Toolbar section"":#search_and_nav_search_toolbar_section |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_number_3.png(Result section)! Result section | See section ""Result section"":#search_and_nav_search_result_section |
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h3(#search_and_nav_search_toolbar_section). Toolbar section
|
|
|
+
|
|
|
+The toolbar section consists of ten buttons with the following functionalities:
|
|
|
+
|
|
|
+|_ Button |_ Action |_ Functionality |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_redo.png(Redo search)! | Redo search |Executes the same search again on the possibly changed model. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_stop.png(Cancel searching)! | Cancel searching | Cancels a currently running search. The button is active only if a search run is being executed. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_search.png(History)!!(inlinemediaobject)images/search_and_nav_icon_list.png(History)! | 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. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_pin.png(Pin search)! | Pin search | Pins the results view. Future search results will be shown in a new search view, instead of rewriting the pinned search view. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_collapse.png(Collapse all)! | Collapse all | Collapses the search result tree and displays the root entries only. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_expand.png(Expand all)! | Expand all | Expands the search result tree and displays all search result entries. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_menu.png(Search menu)! | Search menu |Contains various search options. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_minimize.png(Minimize)! | Minimize |Minimizes the search view and all its sibling views. A "restore" symbol is shown in a sidebar. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_maximize.png(Maximize)! | Maximize |Maximizes the search view and all its sibling views to the full window size. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_icon_restore.png(Restore)!| Restore | Undoes the _Maximize_ function. This button is shown only if the search view is maximized. |
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h3(#search_and_nav_search_result_section). Result section
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+!(full)images/search_and_nav_result_section_actions.png(Result section actions)!
|
|
|
+
|
|
|
+You can perform certain actions on the entries in the first column:
|
|
|
+
|
|
|
+|_. |_. Action |_. Function |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_letter_a.png(A)! | Click on the !(inlinemediaobject)images/search_and_nav_icon_collapse_children.png(collapse children)! button | "Closes" the node and collapses all child nodes. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_letter_b.png(B)! | Click on the !(inlinemediaobject)images/search_and_nav_icon_expand_children.png(expand children)! button | "Opens" the node and expands its immediate child nodes. |
|
|
|
+| !(inlinemediaobject)images/search_and_nav_letter_c.png(C)! | 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. |
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h2(#search_and_nav_finding_references). Finding references
|
|
|
+
|
|
|
+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 _State Behavior_ editor
|
|
|
+
|
|
|
+This will search for usages of the same element in the local statechart and display them in the "search view":search_and_nav_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.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h2(#search_and_nav_differences_1). Differences between "Find references" and "Search dialog"
|
|
|
+
|
|
|
+As written 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 matched 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.
|
|
|
+
|
|
|
+###. FIXME (RKL): It puzzles me that finding references not only finds references, but also finds definitions. Consequently, the function should be called "find occurrences".
|
|
|
+
|
|
|
+!images/search_and_nav_differences_model.png(Example Model)!
|
|
|
+
|
|
|
+|_. Search operation |_. Results |
|
|
|
+| _Find references_ on variable _test_ in the default (unnamed) interface| Finds two matches:<ul><li>Entry action in the *test* state using the _test_ variable</li><li>Definition of the _test_ variable in the unnamed interface</li></ul> |
|
|
|
+| _Find references_ on variable _test_ in named interface _first_| Finds one match:<ul><li>Definition of the _test_ variable in the named interface _first_</li></ul> |
|
|
|
+| _Find references_ on state *test* | Finds one match:<ul><li>The *test* state itself</li></ul> |
|
|
|
+| _Search Dialog_ with the same settings as in section ""Search view"":#search_and_nav_search_view and the search string _"test"_ | Finds four matches:<ul><li>Entry action in the *test* state using the _test_ variable</li><li>Definition of the _test_ variable in the unnamed interface</li><li>Definition of the _test_ variable in the named interface _first_</li><li>The *test* state</li></ul> |
|
|
|
+| _Search Dialog_ with the same settings as in section ""Search view"":#search_and_nav_search_view and the search string _"first.test"_ | Finds one match:<ul><li>Definition of the _test_ variable in the named interface _first_</li></ul> |
|
|
|
+| _Search Dialog_ with almost the same settings as in section ""Search view"":#search_and_nav_search_view, but with _Search for declarations_ deactivated, and with the search string _"test"_ | Finds match:<ul><li>The *test* state</li></ul> |
|
|
|
+| _Search Dialog_ with almost the same settings as in section ""Search view"":#search_and_nav_search_view, but with _Search for states/regions_ deactivated, and with the search string _"test"_ | Finds three matches:<ul><li>Entry action in the *test* state using the _test_ variable</li><li>Definition of the _test_ variable in the unnamed interface</li><li>Definition of the _test_ variable in the named interface _first_</li></ul> |
|
|
|
+
|
|
|
+###. FIXME: Why is the entry action not found in case 6?
|
|
|
+
|
|
|
+As can be seen in this case the search dialog has problems with searching references for the variable _test_ in the unnamed interface.
|
|
|
+
|
|
|
+###. FIXME: An explanation for the last sentence is missing.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+h2(#search_and_nav_open_model_element). Open model element
|
|
|
+
|
|
|
+_Open model element_ is another kind of searching method. It can be used to quickly navigate to states and regions. To access _Open model element_, use the shortcut @[Ctrl+Shift+Q]@ or select _Navigate → Open model element_ in the main menu.
|
|
|
+
|
|
|
+By doing so, the dialog shown in the next screenshot will open up.
|
|
|
+
|
|
|
+!images/search_and_nav_open_model_element_dialog.png(Open model element)!
|
|
|
+
|
|
|
+It consists of one input element !(inlinemediaobject)images/search_and_nav_number_1.png(Searchbar)! and two output elements !(inlinemediaobject)images/search_and_nav_number_2.png(Result list)! / !(inlinemediaobject)images/search_and_nav_number_3.png(Result location)!.
|
|
|
+
|
|
|
+A search operation done with _Open model element_ is equivalent to ""Searching via search dialog"":#search_and_nav_searching_via_search_dialog with the following setting:
|
|
|
+
|
|
|
+|_. Setting |_. Value |
|
|
|
+| _Search string_|same as in !images/search_and_nav_number_1.png(Searchbar)! |
|
|
|
+| _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 slight, but noticeable. The results will promptly appear in !(inlinemediaobject)images/search_and_nav_number_2.png(Result list)! while typing your search string in !(inlinemediaobject)images/search_and_nav_number_1.png(Searchbar)!. The hierarchy for the selected result is displayed in !(inlinemediaobject)images/search_and_nav_number_3.png(Result location)! as a text instead of using a tree.
|
|
|
+
|
|
|
+Navigating to a result can be done by double clicking the result or pressing _OK_ or @[Enter]@ on an selected match.
|
|
|
+
|
|
|
+After doing so, the match will be saved. On reopening the dialog, saved model elements that match the new search string will be displayed at the top of unsaved elements making it easier to navigate to them again at a later time.
|
|
|
+!images/search_and_nav_open_model_element_dialog_saved_elements.png(Saved Elements)!
|
|
|
+
|
|
|
+Saved elements can be removed from history via selecting them and pressing @[Del]@ or right-click on a saved element and choosing _Remove from history_ in the context menu.
|
Thomas Kutz
