PLECS 1.3 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 three 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('lename') [, 'on']) reads an image from the file lename in the MATLAB path and displays it on the mask icon. 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 and a variable name. The prompt provides information that helps the user identify the purpose of a parameter. The variable name specifies the the variable that is to store the parameter value.

Mask parameters appear on the dialog box as edit fields in the order they appear in the prompt list. 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.

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.