Use Advanced Techniques to Customize Block Display

This example shows how you can use block layout annotation and enumerations to improve usability of a custom block.

The following source code for the DCMotorWithGroups component includes declaration blocks for nodes and user-visible parameters, as well as control logic and annotations. The source code in this example does not include sections of code that have no effect on the block dialog box display, such as other declarations, intermediates, branches, and equations.

component DCMotorWithGroups
% DC Motor
% This block represents the electrical and torque characteristics of a
% DC motor.
%
% When a positive current flows from the electrical + to - ports, a
% positive torque acts from the mechanical C to R ports. Motor torque
% direction can be changed by altering the sign of the back-emf
% constant.

nodes
    p = foundation.electrical.electrical; % +:top
    n = foundation.electrical.electrical; % -:bottom
    R = foundation.mechanical.rotational.rotational; % R:top
    C = foundation.mechanical.rotational.rotational; % C:bottom
end

parameters
    Ra = {3.9, 'Ohm'};          % Armature resistance
    La = {12e-6, 'H'};          % Armature inductance
    Kv = {0.072e-3, 'V/rpm'};   % Back-emf constant
    J = {0.01, 'g*cm^2'};       % Rotor inertia
    lam = {0, 'N*m/(rad/s)'};   % Rotor damping
    speed0 = {0, 'rpm'};        % Initial rotor speed
    i_noload = {0, 'A'};        % No-load current
    V_i_noload = {1.5, 'V'};    % DC supply voltage when measuring no-load current
end

% Rotor damping control parameter
parameters
    r_damp = damping.direct;    % Rotor damping parameterization
end

% Conditional parameter visibility for Rotor damping parameterization
if r_damp == damping.direct
    annotations
        [i_noload,V_i_noload]: ExternalAccess=none;
    end
else
    annotations
        [lam]: ExternalAccess=none;
    end
end

annotations
    UILayout = [UIGroup("Electrical Torque",Ra,La,Kv,r_damp,i_noload,V_i_noload)
                UIGroup("Mechanical",J,lam,speed0)]
end

% Declarations with (ExternalAccess=none), branches, intermediates, equations

end

The UILayout annotation defines two groups, Electrical Torque and Mechanical, each with a list of parameters. When you generate a block from the DCMotorWithGroups component, each UIGroup becomes a separate section in the block dialog box, the title string serves as the title of the section, and these parameters appear under that section in listed order.

In addition, the DCMotorWithGroups component provides two methods to specify rotor damping:

• Directly, using the Rotor damping parameter

• By specifying no-load current values instead, using two other parameters: No-load current and DC supply voltage when measuring no-load current

The if statement in the component source specifies the control logic for conditional parameter visibility, depending on the selected value of the control parameter, r_damp (Rotor damping parameterization). The control parameter uses an enumeration that is located in a separate file, damping.m:

classdef damping < int32
   enumeration
     direct (0)
     derived (1)
   end
   methods(Static)
       function map = displayText()
         map = containers.Map;
         map('direct') = 'By damping value';
         map('derived') = 'By no-load current';
       end
   end
end

This enumeration file can be located either in same folder as the component file or on the MATLAB^® path. For more information, see Specifying Display Strings for Enumeration Members.

In the resulting block dialog, the Rotor damping parameterization parameter has a drop-down list of values:

• By damping value

• By no-load current

By damping value is the default value.

When you generate a block from the DCMotorWithGroups component, the block dialog box groups the parameters under two sections:

If you set the Rotor damping parameterization parameter to By no-load current, two additional parameters appear in the Electrical Torque section, and the Rotor damping parameter in the Mechanical section is hidden.

Note that in the Electrical Torque section, the No-load current and DC supply voltage when measuring no-load current parameters appear below the Rotor damping parameterization parameter, even though they were declared earlier, in a separate declaration block. If the component was not using the block layout annotation, you could have achieved the same effect by changing the parameter declaration order, but that would have detracted from code readability.