Customizing the Block Name and Appearance

Default Block Display

When you build a custom block, the block name and the parameter names in the block dialog box are derived from the component file elements. The default block icon in the custom library is a rectangle displaying the block name. Ports are based on the nodes, inputs, and outputs defined in the component file.

The following example shows a component file, named spring.ssc, and the resulting library block and dialog box.

component spring
  nodes
    r = foundation.mechanical.rotational.rotational;
    c = foundation.mechanical.rotational.rotational;
  end
  parameters
    k = { 10, 'N*m/rad' };
  end
  variables
    theta = { 0, 'rad' };
    t = { 0, 'N*m' };
    w = { 0, 'rad/s' };
  end
  function setup
    if k < 0
      error( 'Spring rate must be greater than zero' );
    end
    through( t, r.t, c.t );
    across(  w, r.w, c.w );
  end
  equations
    t == k * theta;
    w == theta.der;
  end
end

If you click the View source for spring link, the spring.ssc file opens in the MATLAB Editor window.

The following sections show you how to annotate the component file to improve the block cosmetics. You can provide meaningful names for the block itself and its parameters in the dialog box, as well as supply a short description of its purpose. You can also substitute a custom block icon for the default image and change the names and the default orientation of the ports.

Back to Top

How to Customize the Block Name

To provide a more descriptive name for the block than the name of the component file, put it on a separate comment line just below the component declaration. The comment line must begin with the % character. The entire content of this line, following the % character, is interpreted as the block name and appears exactly like that in the block icon and at the top of the block dialog box.

For example, if you have the following component file:

component spring
%Rotational Spring
...
end

these are the resulting block icon and dialog box:

Back to Top

How to Describe the Block Purpose

The previous section describes how the comment line immediately following the component declaration is interpreted as the block name. Any additional comments below that line are interpreted as the block description. You can have more than one line of description comments. Each line must be no longer than 80 characters and must begin with the % character. The entire content of description comments will appear in the block dialog box and in the Library Browser.

For example, if you have the following component file:

component spring
%Rotational Spring
% This block implements a simple rotational spring.
...
end

this is the resulting block dialog box:

To create a paragraph break in the block description, use a blank commented line:

% end of one paragraph
% 
% beginning of the next paragraph

Back to Top

How to Specify Meaningful Names for the Block Parameters

You can specify the name of a block parameter, the way you want it to appear in the block dialog box, as a comment immediately following the parameter declaration. It can be located on the same line or on a separate line. The comment must begin with the % character.

For example, if you have the following component file:

component spring
%Rotational Spring
% This block implements a simple rotational spring.
...
 parameters
    k = { 10, 'N*m/rad' }; % Spring rate
  end
...
end

this is the resulting block dialog box:

Back to Top

How to Customize the Names and Locations of the Block Ports

Block ports, both conserving and Physical Signal, are based on the nodes, inputs, and outputs defined in the component file. The default port label corresponds to the name of the node, input, or output, as specified in the declaration block. The default location of all ports is on the left side of the block icon. The ports are spread equidistantly along the block side.

To control the port label and location in the block icon, add a comment immediately following the corresponding node, input, or output declaration. It can be on the same line or on a separate line. The comment must begin with the % character and be of the format label:location, where label is a string corresponding to the input port name in the block diagram, and location is one of the following strings: left, right, top, bottom. You can locate all ports either on one side of the block or on two opposite sides, for example left and right, or top and bottom. You can omit the location if you want to keep the default location of the port (on the left side).

You can also leave the port label field empty and specify just the location. In this case, the port will not have its name displayed. For example, the following syntax suppresses the port label and locates it on the top of the block icon:

    r = foundation.mechanical.rotational.rotational; % :top

If you specify an empty comment string after a node, input, or output declaration, the corresponding port will not be labelled and will be located on the left side of the block icon.

The following are examples of node declarations and the resulting block icons.

nodes
   r = foundation.mechanical.rotational.rotational; 
   c = foundation.mechanical.rotational.rotational; 
end 

nodes
   r = foundation.mechanical.rotational.rotational; % rod
   c = foundation.mechanical.rotational.rotational; % case
end 

nodes
   r = foundation.mechanical.rotational.rotational; 
   c = foundation.mechanical.rotational.rotational; % c:right
end 

nodes
   r = foundation.mechanical.rotational.rotational; % rod
   c = foundation.mechanical.rotational.rotational; % case:right
end 

nodes
   r = foundation.mechanical.rotational.rotational; % rod
   c = foundation.mechanical.rotational.rotational; % :right
end 

nodes
   r = foundation.mechanical.rotational.rotational; % 
   c = foundation.mechanical.rotational.rotational; % case:right
end 

Back to Top

How to Customize the Block Icon

If the subpackage containing the component file (for example, spring.ssc) also contains a file named spring.img, where img is one of the supported image file formats (such as jpg , bmp, or png), then that image file is used for the icon representing this block in the custom library.

The following image file formats are supported:

• jpg

• bmp

• png

If there are multiple image files, the formats take precedence in the order listed above. For example, if the subpackage contains both spring.jpg and spring.bmp, spring.jpg is the image that will appear in the custom library.

Specifying Scaling and Rotation Properties of the Custom Block Icon

When you use an image file to represent a component in the custom block library, the following syntax in the component file lets you specify the scaling and rotation properties of the image file:

component name
% [ CustomName [ : scale [ : rotation ] ] ] 
...

where

For example, the following syntax

component spring
% Rotational Spring : 0.5 : fixed

specifies that the spring image size is scaled to half of its default size and always stays in its default orientation, regardless of the block rotation.

Back to Top

Example — Customized Block Display

The following shows a complete example of a component file with annotation and the resulting library block and dialog box. The file is named spring.ssc, and the package contains the image file spring.jpg, as described in the previous section, How to Customize the Block Icon.

component spring
% Rotational Spring
% This block implements a simple rotational spring.
  nodes
    r = foundation.mechanical.rotational.rotational; % rod
    c = foundation.mechanical.rotational.rotational; % case:right
  end
  parameters
    k = { 10, 'N*m/rad' }; % Spring rate
  end
  variables
    theta = { 0, 'rad' };
    t = { 0, 'N*m' };
    w = { 0, 'rad/s' };
  end
  function setup
    if k < 0
      error( 'Spring rate must be greater than zero' );
    end
    through( t, r.t, c.t );
    across(  w, r.w, c.w );
  end
  equations
    t == k * theta;
    w == theta.der;
  end
end

Back to Top

How to Generate Custom Block Libraries from Simscape Component Files

Checking File and Model Dependencies

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit