Documentation Center

  • Trial Software
  • Product Updates

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
  end
  branches
    t : r.t -> c.t;
  end
  equations
    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

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

nameComponent name
CustomNameCustomized block name, specified as described in Customize the Block Name. Leading and trailing white spaces are removed.
scaleA 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.

rotationSpecifies 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.

Custom 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. This example is an illustration of all the techniques described in Customizing the Block Name and Appearance.

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' };  % Deformation
    t = { 0, 'N*m' };      % Torque
    w = { 0, 'rad/s' };    % Angular velocity
  end
  function setup
    if k < 0
      error( 'Spring rate must be greater than zero' );
    end
  end
  branches
    t : r.t -> c.t;
  end
  equations
    w == r.w - c.w;
    t == k * theta;
    w == theta.der;
  end
end

Was this topic helpful?