Dials & Gauges Blockset

Updating Multiple Portions of a Pie Chart

This example model allows you to control four portions of a pie chart independently using four sliders. The model uses the Dynamic Pie block and four Horizontal Slider blocks. Internally, the model uses an M-file S-function to drive the Dynamic Pie block.

To open this example, enter dng_pie in the MATLAB Command Window. Run the simulation and then move the sliders using your mouse.

These sections describe how the model works:

• How PortionID Values Correspond to Portions of the Pie
• Configuration of the Dynamic Pie Block
• How the S-Function Updates the Pie
• Initial Portion Sizes in the Model

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 S-function that assigns the set of PortionValue parameters ensures that the percentages for all portions add up 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 on the Dynamic Pie block and choose Control Display Properties.
2. Click on the Portions tab.
3. Set PortionID to the ID number you want to investigate: 0, 1, 2, or 3 in this case.
4. Change the PortionValue parameter while watching which portion on the block changes in size.

The table below summarizes what the procedure reveals.

PortionID	Portion on Block
0	Red portion
1	Yellow portion
2	Magenta portion
3	Green portion

For more information about ID properties, see Understanding ID Properties.

Configuration of the Dynamic Pie Block

In the model, a vector containing the four slider values enters the Dynamic Pie block. While the simulation is running, an S-function called dng_pie_sfun.m uses the vector to make the Dynamic Pie block reflect the slider 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 on the block and choose Block Parameters.

  

• The block is driven by a customized S-function, dng_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 choose Edit -> Look under mask from the model window's menu.

  

The S-function dng_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 dng_pie_sfun.m are also similar to sfuntmpl.m, which is an M-file S-function template included in the Simulink distribution. Many features of that S-function template are not required for controlling blocks in the Dials & Gauges Blockset, which simplifies the task of writing S-functions for use with the blockset. For more information about S-functions in general, see the Writing S-Functions documentation.

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.
2. Choose Edit -> Link options -> Disable link.
3. Choose Edit -> Link options -> Break link.

How the S-Function Updates the Pie

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

• Receives the vector input signal that enters 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, Simulink invokes the S-function and passes it the vector that enters the Dynamic Pie block. Within the S-function, the vector is called u. Simulink also passes to the S-function a handle of the Dynamic Pie ActiveX 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 dng_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 customized dng_pie@Dynamic_Pie.ax file that contains the configuration information for the instance of the Dynamic Pie block in the dng_pie model. For more information about .ax files, see Saving the Model.

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 slider blocks, and then save the model to make Simulink record the blocks' configurations in .ax files.

Simulating a Multiple-Needle Stopwatch

Saving and Reusing a Customized Control