Documentation

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 DCMotorWithTabs component shows 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 DCMotorWithTabs
% 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 DCMotorWithTabs component, each UIGroup becomes a tab in the block dialog box, the title string serves as the title of the tab, and the listed parameters appear on that tab, in list order.

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

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, 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 is the default value.

When you generate a block from the DCMotorWithTabs component, the block dialog box has two tabs:

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

Note that in the Electrical Torque tab, 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.

See Also

annotations

Related Topics

• Customizing the Block Name and Appearance
• Defining Conditional Visibility of Component Members
• Enumerations