Accelerating the pace of engineering and science

# Documentation

## Controlling Multiple Graphical Elements

This section describes techniques for displaying multiple input values simultaneously and dynamically on a gauge block that includes multiple graphical elements. Examples of multiple-component gauge blocks include these preconfigured blocks:

• Multiple Scales in the Linear Gauges library

• Pie Chart and Dynamic Pie in the Percent Indicators library

• Analog Clock and Stop Watch in the Angular Gauges library

### Simulating a Multiple-Needle Stopwatch

This example model simulates a typical sailing stopwatch. The model uses the Stop Watch block, which displays three needles on individual angular scales. The needles mark simulation time simultaneously, as follows:

• The large needle spans 1 minute.

• The small needle on the left spans 1 second.

• The small needle on the right spans 15 minutes.

To open this example, enter gauges_stopwatchgauges_stopwatch in the MATLAB® Command Window. Run the simulation and watch how the three needles move.

These sections describe how the model works:

#### How NeedleID Values Correspond to Needles

To explain how the model controls three needles, this section first explains how the block makes its needles accessible to you. Each needle on the block has an associated pair of NeedleID and Value parameters, where

• NeedleID is a number that distinguishes that needle from other needles on the block.

• Value is the numerical value for that needle along its angular scale.

You can view or control these parameters via the Needles panel of the block's ActiveX® Control Properties dialog box. To find out which needle and range of values correspond to a given ID number, use this procedure:

1. Right-click the Stop Watch block and choose Control Display Properties.

2. Click the Needles tab.

3. Set NeedleID to the ID number you want to investigate, here 0, 1, or 2.

The dialog box looks like this:

4. Change the Value parameter while watching which needle on the block moves. Drag the Value slider to its extremes to find out the minimum and maximum values for the needle:

NeedleIDNeedle on BlockRange of Values
0Large needle[0, 60] seconds
1Small needle on right[0, 15] minutes
2Small needle on left[0, 5] fifths of a second

#### Configuration of the Stop Watch Block

After you run the model, the number 6 appears near the connector line that represents the input to the Stop Watch block. This indicates that the signal on that line is a vector of length 6. To understand why, right-click the Stop Watch block and choose Block Parameters.

The Input property field in the dialog box is set to:

`NeedleID,NeedleValue,NeedleID,NeedleValue,NeedleID,NeedleValue`

By contrast, the default value for this property in the Angular Gauges library is NeedleValue.

The comma-separated list in this example model causes the Stop Watch block to use the six values in its vector input signal to assign these parameters to the block, in sequence:

• The ID number, 0, of the large needle

• The numerical value for the large needle

• The ID number, 2, of the small needle on the left

• The numerical value for the small needle on the left

• The ID number, 1, of the small needle on the right

• The numerical value for the small needle on the right

 Note:   It is important that each needle's ID number precede its numerical value. Referring first to the ID number tells the block which needle to apply changes to.

#### Preparing the Input Signal for the Stop Watch Block

The model aims to reflect the time on the Stop Watch block. However, the model has to process the Clock block's output to prepare it for the Stop Watch block. Double-click the Subsystem block to open it. The subsystem performs these key tasks:

• Processes the Clock block's output value, in seconds, into numerical values suitable for the unit, scale, and range of each needle. To do this, the block performs these computations:

• Reduces modulo 60, to get the large needle's value.

• Reduces modulo 1 and then multiplies by 5, to get the left needle's value (ranging between 0 and 5).

• Reduces modulo 15*60 and then divides by 60, to get the right needle's value (ranging between 0 and 15).

• Forming a six-element vector corresponding to the comma-separated list in Configuration of the Stop Watch Block. To form this vector, the subsystem uses three Constant blocks, the three processed Clock block signals, and a Mux block.

### Updating Multiple Portions of a Pie Chart

This example model enables you to control four portions of a pie chart independently using four sources. The model uses the Dynamic Pie block. Internally, the model uses a MATLAB S-function to drive the Dynamic Pie block. Compared to the technique in Simulating a Multiple-Needle Stopwatch, the S-function technique is more complicated but also more flexible and powerful.

To open this example, enter gauges_piegauges_pie in the MATLAB Command Window. Change the values of the Constant blocks to alter the composition of the pie chart. You must close the dialog by clicking OK to see the result of your changes.

These sections describe how the model works:

#### How PortionID Values Correspond to Portions of the Pie

To explain how the model controls four portions, this section first explains how the block makes its portions accessible to you. Each portion on the block has an associated pair of PortionID and PortionValue parameters, where

• PortionID is a number that distinguishes that portion from other portions on the block.

• PortionValue is the numerical value for that portion, as a percentage. The PortionValue S-function normalizes the sum of the portion percentages to 100.

You can view or control these parameters via the Portions panel of the block's ActiveX Control Properties dialog box. To find out which portion corresponds to a given ID number, use this procedure:

1. Right-click the Dynamic Pie block and choose Control Display Properties.

2. Click the Portions tab.

3. Set PortionID in the top left corner to the ID number you want to investigate: 0, 1, 2, or 3 in this case.

The dialog box looks like this:

4. Change the PortionValue parameter while watching which portion on the block changes in size:

PortionIDPortion on Block
0Red portion
1Yellow portion
2Magenta portion
3Green portion

#### Configuration of the Dynamic Pie Block

In the model, a vector containing the four constant values is the input to the Dynamic Pie block. While the simulation is running, an S-function called gauges_pie_sfun.m uses the vector to make the Dynamic Pie block reflect the constant values. While the behavior of the S-function is discussed below (How the S-Function Updates the Pie), this section describes how the Dynamic Pie block is linked with the S-function.

The Dynamic Pie block in this model is a customized copy of the original one in the Percent Indicators library. The customized copy differs from the original in these ways:

• The Input property field in the Block Parameters dialog box is blank. This is because the block is being updated by an S-function that ignores the data in the Input property field. To see the Input property field, right-click the block and choose Block Parameters:

• The block is driven by a customized S-function, ax_pie_sfun.m, rather than the S-function that drives the original library block. To see this, select the outer border of the block and select Diagram > Mask > Look Under Mask:

The S-function ax_pie_sfun.m is a customized version of ax_strip_sfun.m, which is an S-function designed to drive the Strip Chart block. Many parts of ax_pie_sfun.m are also similar to sfuntmpl.m, which is a MATLAB S-function template. The S-function variable hActx is used in the Initialization text box in the Block Parameters dialog box.

Many features of that S-function template are not required for controlling Gauges Blockset™ blocks, which simplifies the task of writing S-functions for use with the blockset.

If you were building this model yourself starting from the original library block, then you would have to break the library link before changing the values in the S-Function dialog box shown previously. To break the library link for a library block, use this procedure:

1. Select the outer border of the block.

#### How the S-Function Updates the Pie

While the simulation is running, the S-function ax_pie_sfun.m drives the Dynamic Pie block. In particular, this S-function

• Receives the vector that is the input signal to the Dynamic Pie block

• Normalizes the vector so that the values add up to 100

• Updates each portion of the pie to reflect the corresponding number from the vector

Receiving the Vector Input Signal.  During the simulation, the Simulink® engine invokes the S-function and passes it the Dynamic Pie block's input vector. Within the S-function, the vector is called u. The engine also passes to the S-function a handle of the Dynamic Pie control. The handle is called hActx.

Normalizing the Input Vector.  The S-function uses the code below to normalize the vector u so that its elements add up to 100:

```% First make sure there is no division by zero.
if sum(u)==0
u=u+0.001;
end

% Now perform the normalization.
u = 100/sum(u).*u;
```

Updating the Dynamic Pie Block.  After sum(u) is 100, the S-function updates the portions of the Dynamic Pie block by setting each one to the corresponding element of u. The code uses the handle hActx to access the PortionID and PortionValue parameters of the Dynamic Pie block.

```% Loop through the portions and update their values.
%
if (length(u) ~= 0)
for n=1:length(u)
hActx.PortionID = n-1;
hActx.PortionValue = u(n);
end
end
```

#### Initial Portion Sizes in the Model

When you first open the gauges_pie model, the portions of the pie have equal sizes, unlike the portions in the default instance of the Dynamic Pie block in the Percent Indicators library. The equal-sized portions result from the configuration from which the model was saved.

If you were building this model yourself starting from the original library blocks, then you would first run the model to make the portion sizes reflect the values on the Constant blocks, and then save the model to record the blocks' configurations.