Defining Conditional Visibility of Component Members
The annotations
section in a component file lets you
control visibility of component members, such as parameters and nodes, in block icons and
dialog boxes. When you declare a component member, the ExternalAccess
attribute sets the visibility of the member in the user interface, that is, in block dialog
boxes, simulation logs, variable viewer, and so on. The
annotations
section serves a similar purpose, but it is
especially useful for block variants because it lets you define conditional visibility of
component members based on a predicate condition.
When you define component variants using conditional declarations, certain parameters,
variables, or ports can be used in one block variant but not in others. For example, you have
a component that models hydraulic pipelines with circular and noncircular cross sections. For
a circular pipe, you need to specify its internal diameter. For a noncircular pipe, you need
to specify its hydraulic diameter and pipe cross-sectional area. You can now use the
annotations
section to control the visibility of these
parameters in the block dialog box:
component MyPipe
parameters
circular = true; % Circular pipe?
d_in = { 0.01, 'm' }; % Pipe internal diameter
area = { 1e-4, 'm^2' }; % Noncircular pipe cross-sectional area
D_h = { 1.12e-2, 'm' }; % Noncircular pipe hydraulic diameter
end
if circular
% Hide inapplicable parameters
annotations
[area, D_h] : ExternalAccess=none;
end
equations
% first set of equations, for circular pipe
end
else
% Hide inapplicable parameter
annotations
d_in : ExternalAccess=none;
end
equations
% second set of equations, for noncircular pipe
end
end
[...] % other parameters, variables, branches, equations
end
Similar to other types of conditional declarations, a predicate of a conditional
annotation must be a parametric expression that evaluates to true or false. However, there is
an additional restriction that all the parameters used in the predicate of a conditional
annotation must be either of type logical or enumerated. In this example, the
circular
parameter is of type logical.
The annotations
section lets you control visibility of
the following component members:
Parameters
Variables
Nodes
Inputs
Outputs
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
For more information on using custom block icons, see Customize the Block Icon.
Rules and Restrictions
The predicate of a conditional annotation must be a parametric expression that evaluates to true or false. All the parameters used in the predicate of a conditional annotation must be either of type logical or enumerated.
Member attributes must be uniquely defined, which means that the same member cannot be
declared more than once, with different values of the same attribute. The only exception to
this rule is the use of ExternalAccess
attribute in the
annotations
section. You can declare a component
member with a certain value of ExternalAccess
, and then specify a
different ExternalAccess
attribute value in the
annotations
section, for example:
component MyPipe
parameters
circular = true; % Circular pipe?
end
parameters(ExternalAccess=none)
d_in = { 0.01, 'm' }; % Pipe internal diameter
[...]
end
if circular
% Expose pipe diameter
annotations
d_in : ExternalAccess=modify;
end
[...]
In case of conflict, the ExternalAccess
attribute value specified in
the annotations
section overrides the value specified
for that member in the declaration section. For a complete component example using this
approach, see Component Variants — Thermal Resistor.