Main Content

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.

Related Topics