Navigate to Simulink Objects from External Documents

Requirements Toolbox™ includes several functions that simplify creating navigation interfaces in external documents. The external application that displays your document must support an application programming interface (API) for communicating with the MATLAB^® software.

Provide Unique Object Identifiers

Whenever you create a requirement link for a Simulink^® or Stateflow^® object, Requirements Toolbox uses a globally unique identifier for that object. This identifier identified the object. The identifier does not change if you rename or move the object, or add or delete requirement links. Requirements Toolbox uses the unique identifier only to resolve an object within a model.

Use the `rmiobjnavigate` Function

The rmiobjnavigate function identifies the Simulink or Stateflow object, highlights that object, and brings the editor window to the front of the screen. When you navigate to a Simulink model from an external application, invoke this function.

The first time you navigate to an item in a particular model, you might experience a slight delay while the software initializes the communication API and the internal data structures. You do not experience a long delay on subsequent navigation.

Determine the Navigation Command

To create a requirement link for a Simulink or Stateflow object, at the MATLAB prompt, use the following command to find the navigation command, where obj is a handle or a uniquely resolved name for the object:

[ navCmd, objPath ] = rmi('navCmd', obj);

The return values of the navCmd method are:

navCmd — A character vector that navigates to the object when evaluated by the MATLAB software.
objPath — A character vector that identifies the model object.

Send navCmd to the MATLAB software for evaluation when navigating from the external application to the object obj in the Simulink model. Use objPath to visually identify the target object in the requirements document.

Use the ActiveX Navigation Control

Requirements Toolbox uses software that includes a special Microsoft^® ActiveX^® control to enable navigation to Simulink objects from Microsoft Word and Excel^® documents. You can use this same control in any other application that supports ActiveX within its documents.

The control is derived from a push button and has the Simulink icon. There are two instance properties that define how the control works. The tooltipstring property is displayed in the control tooltip. The MLEvalCmd property is the character vector that you pass to the MATLAB software for evaluation when you click the control.

Typical Code Sequence for Establishing Navigation Controls

When you create an interface to an external tool, you can automate the procedure for establishing links. This way, you do not need to manually update the dialog box fields. This type of automation occurs as part of the selection-based linking for certain built-in types, such as Microsoft Word and Excel documents.

To automate the procedure for establishing links:

Select a Simulink or Stateflow object and an item in the external document.
Invoke the link creation action either from a Simulink menu or command, or a similar mechanism in the external application.
Identify the document and current item using the scripting capability of the external tool. Pass this information to the MATLAB software. Create a requirement link on the selected object using Requirements Toolbox API as follows:
1. Create an empty link structure using the following command:
```
rmi('createempty')
```
2. Fill in the link structure fields based on the target location in the requirements document.
3. Attach the link to the object using the following command:
```
rmi('cat')
```
Determine the MATLAB navigation command that you must embed in the external tool, using the navCmd method:
```
[ navCmd, objPath ] = rmi('navCmd',obj)
```
Create a navigation item in the external document using the scripting capability of the external tool. Set the MATLAB navigation command in the property.
When using ActiveX navigation objects provided by the external tool, set the MLEvalCmd property to the navCmd and set the tooltipstring property to objPath.

You define the MATLAB code implementation of this procedure as the SelectionLinkFcn function in the link type definition file. For examples of document interface definitions, you can view the built-in document interface definitions in the fullfile(matlabroot,"toolbox","slrequirements","slrequirements","linktype_examples") directory:

linktype_rmi_doors.m
linktype_rmi_excel.m
linktype_rmi_html.m
linktype_rmi_text.m