Customizing the Block Name and Appearance

Default Block Display

When you generate a custom block from a Simscape™ component file, the block name and the parameter and variable names in the block dialog box are derived from the component file elements. The default block icon 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
  branches
    t : r.t -> c.t;
  end
  equations
    assert(k>0)
    w == r.w - c.w;
    t == k * theta;
    w == theta.der;
  end
end

If you click the Source code 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 for its parameters and variables 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.

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:

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

Specify Meaningful Names for the Block Parameters and Variables

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:

Use the same technique to specify meaningful names for the top-level public variables of the component. These variables appear on the Variables tab of the block dialog box, and giving them descriptive names helps with the block-level variable initialization prior to simulation.

For example, if you have the following component file:

component spring
%Rotational Spring
% This block implements a simple rotational spring.
...
  variables
    theta = { value = { 0 , 'rad' }, priority = priority.high }; % Deformation
    t = { 0, 'N*m' };   % Torque
    w = { 0, 'rad/s' }; % Angular velocity
  end
...
end

the resulting Variables tab of the block dialog box looks like this:

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.

SyntaxBlock Icon

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 

Customize the Block Icon

The default block icon is a rectangle displaying the block name. You can replace this default icon with a custom image file. For information on supported file formats and image properties, see Supported File Formats.

There are two ways to specify a custom block icon:

  • Explicitly, using the annotations section in the component file. This is the recommended way because it provides more flexibility. You can keep the image files in a separate folder and specify relative paths for the block icons. You can also specify conditional custom icons for different block variants. For more information, see Using Annotations.

  • Implicitly, using the file naming conventions. This method is convenient if you ship complete library packages to customers. For more information, see Using File Naming Conventions.

Using Annotations

Use the annotations section in the component file to specify the name of the custom block icon. The file name must contain the file extension. For example:

  annotations
    Icon = 'custom_spring.jpg';
  end

The file name can include a relative path from the folder containing the component file to the folder containing the image file, for example:

  annotations
    Icon = '../../block_icons/custom_spring.jpg';
  end

The annotations section also lets you specify conditional custom icons. This is especially useful if the number of ports changes for different variants. For example:

component MyPipe
  parameters
    thermal_variant = false; % Model thermal effects?
  end
  if thermal_variant 
  % Use icon with additional thermal port
    annotations
       Icon = 'pipe_thermal.jpg';
    end
  else
  % Use regular icon, with two fluid ports
    annotations
       Icon = 'pipe.jpg';
    end
  end
  [...] % Other parameters, variables, nodes, branches, equations
end

Using File Naming Conventions

Instead of explicitly specifying a custom block icon using the annotations section, you can do it implicitly, by placing an image file with the same name as the component in the folder containing the component file.

This method is convenient if you ship complete library packages to customers. For example, if the subpackage containing the component file spring.ssc also contains a file named spring.jpg, then that image file is automatically used for the icon representing this block in the custom library.

The implicit rules for using custom block icons are:

  1. If the annotations section does not explicitly specify a custom icon image, or if that image is not found, the software looks in the folder containing the component file for an image file with the same name as the component.

  2. If there are multiple image files with the same name, the formats take precedence in the order listed in Supported File Formats. For example, if the subpackage contains both spring.jpg and spring.bmp, spring.jpg is the image that will appear in the custom library.

Supported File Formats

The following image file formats are supported for custom block icons:

  • svg

  • jpg

  • bmp

  • png

Caution

Using svg format together with domain-specific line styles can lead to unexpected results, because domain line styles and colors can propagate to parts of the custom block icon. For more information on turning domain-specific line styles on and off, see Domain-Specific Line Styles.

The image type must be an RGB (truecolor) image, stored as an m-by-n-by-3 data array. For more information, see RGB (Truecolor) Images (MATLAB).

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

name

Component name

CustomName

Customized block name, specified as described in Customize the Block Name. Leading and trailing white spaces are removed.

scale

A scalar number, for example, 2.0, which specifies the desired scaling of the block icon. When an image file is used as a block icon, by default its shortest size is 40 pixels, with the image aspect ratio preserved. For example, if your custom image is stored in a .jpg file of 80x120 pixels, then the default block icon size will be 40x60 pixels. If you specify a scale of 0.5, then the block icon size will be 20x30 pixels.

You cannot specify MATLAB expressions for the scale, just numbers.

rotation

Specifies whether the block icon rotates with the block:

  • rotates means that the icon rotates when you rotate the block. This is the default behavior.

  • fixed means that the ports rotate when you rotate the block, but the icon always stays in default orientation.

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.

See Also

Related Topics