PLECS 2.0 Online Help

Masking Subcircuits

Masking a subcircuit allows you to create a custom user interface for a Subcircuit block that hides the underlying schematic, making it appear as an atomic component with its own icon and dialog box. Many of the components in the PLECS component library are in fact masked subcircuits. To mask a subcircuit, select the Subcircuit block, then choose Mask subcircuit from the Edit menu or from the block's context menu. The mask editor appears. The mask editor consists of four tabbed panes that are described in detail below.

Mask Icon

The Icon pane enables you to create icons that show descriptive text or labels, graphics and images.

[Picture]

Mask Icon Drawing Commands

The available drawing commands are described below. If you enter more than one command, the graphic objects are drawn in the order in which the commands appear. In case an error occurs during evaluation of the commands PLECS displays three question marks (? ? ?) in the mask icon.


Note  Unlike with Simulink masks, the PLECS drawing commands do not have access to variables defined in the mask or base workspace.

Text text(’text’) displays a text in the center of the icon.

text(x, y, ’text[, fontsize]) places the text at the coordinates x and y. The optional argument fontsize allows you to specify the font size.

The displayed text does not rotate or flip together with the icon. It is always displayed from left to right and it is centered both horizontally and vertically at its position.

Line line(xvec, yvec) plots the vector yvec against the vector xvec. Both vectors must have the same length. The vectors may contain NaN and inf values. When NaNs or infs are encountered, the line is interrupted and continued at the next point that is not NaN or inf.

Patch patch(xvec, yvec) draws a solid polygon whose vertices are specified by the vectors xvec and yvec. Both vectors must have the same length.

Circle circle(x, y, r) draws a circle at the coordinates x and y with the radius r.

Image image(xvec, yvec, imread(’filename’) [, ’on’]) reads an image from the file filename and displays it on the mask icon. The parameter filename must either be an absolute filename (e.g. C:\images\myimage.png) or a relative filename that is appended to the model's directory (e.g. images\myimage.png). The two-element vectors xvec and yvec specify the minimum and maximum coordinates of the image's extent.

Use the optional flag ’on’ to indicate that the image data should rotate or flip together with the mask icon. By default, this is set to ’off’, and the image data remains stationary.

Mask Icon Coordinates

All coordinates used by the mask drawing commands are expressed in pixels. The origin of the coordinate system is always the center of the block icon; it is moved when the block is resized.

Use the icon frame and/or the terminal locations as reference points in order to position graphic elements. Both the frame and the terminals snap to a grid of 10 by 10 pixels.

Mask Icon Properties

Icon frame The icon frame is the rectangle that encloses the block. You can choose to show or hide the frame by setting the Icon frame property to Visible or Invisible.

Icon transparency The icon can be set to Opaque or Transparent, either hiding or showing the terminal labels underneath the icon.

Mask Parameters

The Parameters pane enables you to define the parameters that will appear in the dialog box of the masked subcircuit.

[Picture]

Prompts and Associated Variables

Mask parameters are defined by a prompt, a variable name and a type. The prompt provides information that helps the user identify the purpose of a parameter. The variable name specifies the variable that is to store the parameter value.

Mask parameters appear on the dialog box in the order they appear in the prompt list. Parameters of type Edit are shown as a text edit field. Parameters of type Combo Box offer a choice of predefined values. The possible values are defined in the Combo Box values field with each line representing one value. Parameters of type Check Box can be set to false or true. Parameters of type Thermal allow to specify a thermal description. See section Thermal Description Parameter for more details.

You can add or remove parameters or change their order by using the four buttons to the left of the prompt list.

Variable Scope

PLECS associates a local variable workspace with each masked subcircuit that has one or more mask parameters defined. Components in the underlying schematics can only access variables that are defined in this mask workspace.

Initialization Commands

The mask initialization commands are evaluated in the mask workspace when a simulation is started. You can enter any valid MATLAB expression, consisting of MATLAB functions, operators, and variables defined in the mask workspace. Variables defined in the base workspace cannot be accessed.

Mask Probe Signals

The Probes pane enables you to define the probe signals that the masked subcircuit will provide to the PLECS Probe. Mask probe signals appear in the probe editor in the order they appear in the mask signal list. You can add or remove signals or change their order by using the four buttons to the left of the signal list.

[Picture]

Mask probe signals are defined as vectors of probe signals from components below the subcircuit mask. For this reason the controls in the lower half of the dialog are identical to those of the probe editor. In order to define a mask signal, select the signal in the list and then drag the desired components into the dialog window. The new components are added to the bottom of the list of probed components. Next, select the components one by one and enable the desired component signals in the list on the right side by using the check boxes.

Mask Documentation

The Documentation pane enables you to define the descriptive text that is displayed in the dialog box of the masked subcircuit.

[Picture]

Mask Type

The mask type is a string used only for purposes of documentation. PLECS displays this string in the dialog box and appends "(mask)" in order to differentiate masked subcircuits from built-in components.

Mask Description

The mask description is informative text that is displayed in the dialog box in the frame under the mask type. Long lines of text are automatically wrapped to fit into the dialog box. You can force line breaks by using the Enter or Return key.

Unprotecting Masked Subcircuits

If you define a mask icon for a Subcircuit block, PLECS automatically protects the block and the underlying schematic. You can no longer resize the Subcircuit block or modify the sub-schematic. The purpose of this protection is to prevent the user from making unintentional changes that might render the icon useless.

If you want to change a masked Subcircuit block, you can unprotect it by choosing Unprotect from the Edit menu or from the block's context menu. You can later protect it again by choosing Protect from the same menus.