Canvas

class mhi.pscad.Canvas

A canvas is a surface where components can be placed and arranged. A “user canvas” is the most general version of a canvas. (T-Line and Cable canvases are more restrictive, permitting only certain types of components.)

The main page of a project is typically retrieved with:

main = project.canvas('Main')

Properties

Canvas.scope

The name of the project (read-only)

New in version 2.0.

Canvas.name

The name of the definition (read-only)

New in version 2.0.

Canvas.parameters(parameters=None, **kwargs) → Dict[str, Any]

Get or set canvas parameters

Canvas Parameters

Param Name	Type	Description
auto_sequence	str	‘MANUAL’, ‘AUTOMATIC’
show_border	bool	Display re-sizing border
monitor_bus_voltage	bool	Display dynamic voltage levels on buses
show_grid	bool	Show connection grid
show_signal	bool	Show all locations tracked in signal table
show_terminals	bool	Show where equipment ports are terminated
show_sequence	bool	Display sequence order numbers
show_virtual	bool	Show virtual wired signal relations
virtual_filter	str	Comma separated signal names to show
animation_freq	int	How often components are redrawn (msec)
orient	str	‘LANDSCAPE’, ‘PORTRAIT’
size	str	‘85X11’, ‘11X17’, ‘17X22’, ‘22X34’, ‘34X44’, ‘100X100’

New in version 2.1.

Canvas.parameter_range(parameter: str)

Get legal values for a setting

New in version 2.1.

Finding Components

The Canvas.find(), Canvas.find_first() and Canvas.find_all() methods are improvements over the original methods which found components by Id attribute. These methods automatically detect the type of the found component(s), and return a control proxy of the correct type.

Canvas.find([[definition,] name,] [layer=name,] [key=value, ...])

Find the (singular) component that matches the given criteria, or None if no matching component can be found. Raises an exception if more than one component matches the given criteria.

Canvas.find_first([[definition,] name,] [layer=name,] [key=value, ...])

Find the first component that matches the given criteria, or None if no matching component can be found.

Canvas.find_all([[definition,] name,] [layer=name,] [key=value, ...])

Find all components that match the given criteria. If no criteria is given, all components on the canvas are returned.

Parameters:

• definition (str) – One of “Bus”, “TLine”, “Cable”, “GraphFrame”, “Sticky”, or a colon-seperated definition name, such as “master:source3” (optional)

• name (str) – the component’s name, as given by a parameter called “name”, “Name”, or “NAME”. If no definition was given, and if the provided name is “Bus”, “TLine”, “Cable”, “GraphFrame”, “Sticky”, or contains a colon, it is treated as the definition name. (optional)

• layer (str) – only return components on the given layer (optional)

• key=value – A keyword list specifying additional parameters which must be matched. Parameter names and values must match exactly. For example, Voltage=”230 [kV]” will not match components with a Voltage parameter value of “230.0 [kV]”. (optional)

Returns:

The list of matching components, or an empty list if no matching components are found.

Return type:

List[Component]

Examples:

c = find_all('Bus'                # all Bus components
c = find_all('Bus10')             # all components named "Bus10"
c = find_all('Bus', 'Bus10')      # all Bus component named "Bus10"
c = find_all('Bus', BaseKV='138') # all Buses with BaseKV="138"
c = find_all(BaseKV='138')        # all components with BaseKV="138"

Canvas.components() → List[Component]

Get a list of all components on the canvas.

This is equivalent to calling Project.find_all(), where no filter criteria is used to select a subset of components.

Returns:

The list of components

Return type:

List[Component]

New in version 2.0.

Finding By Id

These methods are the original methods which find components by Id attribute. Care must be taken to ensure the correct method is used for the type of component, or an incorrect control proxy will be returned.

In almost every case, it is simplier to use the newer find(), find_first(), or find_all() methods.

Canvas.component(iid) → Component

Retrieve a component by ID.

Parameters:

iid (int) – The ID attribute of the component.

New in version 2.0: This command replaces all of the type specific versions.

Creating Components

See also the User Canvas’s Creating … section for creating wires, buses, annotations, graphs and controls.

Canvas.create_component(defn: Union[str, Definition], x: int = 1, y: int = 1, orient: int = 0, **parameters) → Component

Create a new component and add it to the canvas.

Parameters:

• defn (Union[str, Definition]) – Type of component to create

• x (int) – X location of the component (in grid units).

• y (int) – Y location of the component (in grid units).

• orient (int) – Rotation/mirroring of the component

• parameters – key=value pairs

Returns:

The created Component.

New in version 2.0.

Changed in version 2.2: defn accepts a Definition or a string.

Canvas.add_component(library: str, name: str, x: int = 1, y: int = 1, orient: int = 0, **parameters) → Component

Create a new user component and add it to the canvas.

Parameters:

• library (str) – Library the definition may be found in.

• name (str) – Name of the component definition in the library.

• x (int) – X location of the component (in grid units).

• y (int) – Y location of the component (in grid units).

Returns:

The created Component.

Changed in version 2.0: Added orient and **parameters

Clipboard Operations

Canvas.select(*components: Component)

Place specific components in the current selection.

Parameters:

components (list) – the components to be selected.

New in version 2.0.

Canvas.select_components(x1: int, y1: int, x2: int = None, y2: int = None, width: int = None, height: int = None)

Select components in a rectangular area.

If width and height are used, the x1,y1 values are interpreted as the lower-left corner of the region. If both x1,y1 and x2,y2 are given, any opposite corners may be used and the rectangle will be normalized for the user automatically.

All values are in grid coordinates.

Parameters:

• x1 (int) – lower left corner of the selection region

• y1 (int) – lower left corner of the selection region

• x2 (int) – upper right corner of the selection region (optional)

• y2 (int) – upper right corner of the selection region (optional)

• width (int) – width of the selection region (optional)

• height (int) – height of the selection region (optional)

Canvas.clear_selection()

Reset the selection so that no components are selected.

Canvas.copy(*components: Component) → bool

Copy the given list of components, or currently selected components if no components are given, to the clipboard.

Parameters:

*components (List[Component]) – Components to be copied (optional)

Changed in version 2.1: Added optional list of components

Canvas.cut(*components: Component) → bool

Cut the given list of components, or currently selected components if no components are given, to the clipboard.

Parameters:

*components (List[Component]) – Components to be cut (optional)

Changed in version 2.1: Added optional list of components

Canvas.paste(mouse_x: int, mouse_y: int) → bool

Paste the contents of the clipboard into this canvas at the indicated mouse location.

Changed in version 2.1: Added mouse_x and mouse_y

Canvas.delete(*components: Component) → bool

Delete the given list of components, or currently selected components if no components are given.

Parameters:

*components (List[Component]) – Components to be deleted (optional)

Changed in version 2.1: Added optional list of components

Transformations

New in version 2.0.

Canvas.mirror(*components: Component) → bool

Mirror the given list of components, or the currently selected components if no components are given, along the horizontal axis.

Parameters:

*components (List[Component]) – Components to be mirrored (optional)

Canvas.flip(*components: Component) → bool

Flip the given list of components, or the currently selected components if no components are given, along the vertical axis.

Parameters:

*components (List[Component]) – Components to be flipped (optional)

Canvas.rotate_right(*components: Component) → bool

Rotate the given list of components, or the currently selected components if no components are given, 90 degrees clockwise.

Parameters:

*components (List[Component]) – Components to be rotated (optional)

Canvas.rotate_left(*components: Component) → bool

Rotate the given list of components, or the currently selected components if no components are given, 90 degrees counter-clockwise.

Parameters:

*components (List[Component]) – Components to be rotated (optional)

Canvas.rotate_180(*components: Component) → bool

Rotate the given list of components, or the currently selected components if no components are given, 180 degrees.

Parameters:

*components (List[Component]) – Components to be rotated (optional)

Navigation

Canvas.navigate_up() → None

Navigate to parent page

User Canvas

class mhi.pscad.UserCanvas

A user canvas is a surface where components can be placed and arranged.

The main page of a project is typically retrieved with:

main = project.canvas('Main')

Parameters

UserCanvas.parameters(parameters: Dict[str, Any] = None, **kwargs)

Get or set User Canvas parameters

User Canvas Settings

Param Name	Type	Description
auto_sequence	Choice	Sequence Ordering: MANUAL, AUTOMATIC
show_border	Boolean	Bounds
monitor_bus_voltage	Boolean	Bus Monitoring
show_grid	Boolean	Grids
show_signal	Boolean	Signals
show_terminals	Boolean	Terminals
show_sequence	Boolean	Sequence Order Numbers
show_virtual	Boolean	Virtual Wires
size	Choice	Size: 85X11, 11X17, 17X22, 22X34, 34X44, 100X100
orient	Choice	Orientation: PORTRAIT, LANDSCAPE
virtual_filter	Text	Virtual Wires Filter
animation_freq	Integer	Animation Update Frequency

New in version 2.1.

UserCanvas.parameter_range(parameter: str)

Get legal values for a setting

New in version 2.1.

Smart Clipboard

UserCanvas.paste_transfer(mouse_x: int, mouse_y: int) → bool

Paste a component and its definition from the clipboard, so it can be used in this project.

Changed in version 2.0: Component.copy_transfer() is deprecated; simply Canvas.copy() the component(s) to the smart clipboard.

UserCanvas.paste_rename(mouse_x: int, mouse_y: int) → bool

Paste the contents of the clipboard and rename all the components to unique names. All references to the original name will be

New in version 2.0.

Composition

UserCanvas.group(*components: Component) → Component

Group the given list of components into one group component.

Parameters:

*components (List[Component]) – Components to be grouped

Returns:

the Aggregate component

Return type:

Component

UserCanvas.compose_wires(*wires: Wire) → bool

Join connected wire segments into multisegment wires

UserCanvas.decompose_wires(*wires: Wire) → bool

Split all of the segments of the wires into multiple simple wires

Creating …

Methods for creating various components.

New in version 2.0.

Wires

UserCanvas.create_wire((x1, y1), (x2, y2)[, ... (xn, yn) ...])

Create a new wire and add it to the canvas.

If more than two vertices are given, a multi-vertex wire will be created. If any segment is neither horizontal or vertical, additional vertices will be inserted.

Parameters:

*vertices – A series of (X, Y) pairs, in grid units

Returns:

The created wire.

Return type:

Wire

Note

Use UserComponent.get_port_location() to determine the locations to connect the wires to.

Changed in version 2.0: Replaces UserCanvas.add_wire(...)

UserCanvas.create_bus((x1, y1), (x2, y2)[, ... (xn, yn) ...])

Create a new bus and add it to the canvas.

If more than two vertices are given, a multi-vertex bus will be created. If any segment is neither horizontal or vertical, additional vertices will be inserted.

Parameters:

*vertices – A series of (X, Y) pairs, in grid units

Returns:

The created bus.

Return type:

Bus

Note

Use UserComponent.get_port_location() to determine the locations to connect the wires to.

UserCanvas.create_sticky_wire((x1, y1), (x2, y2)[, ... (xn, yn) ...])

Create a sticky wire between two or more vertices.

All vertices will be connected to a central point via a short one grid unit horizontal or vertical segment, followed by a diagonal segment.

Parameters:

*vertices – A series of (X, Y) pairs, in grid units

Returns:

The created sticky wire.

Return type:

StickyWire

Annotations

UserCanvas.create_annotation(x: int = 1, y: int = 1, line1: str = None, line2: str = None) → Component

Create a two-line annotation component.

Parameters:

• x (int) – x-coordinate of the annotation (in grid units)

• y (int) – y-coordinate of the annotation (in grid units)

• line1 (str) – first line of text

• line2 (str) – second line of text

Returns:

the created annotation

Return type:

Component

Changed in version 2.1: Added line1 and line2 parameters

UserCanvas.create_sticky_note(x: int = 1, y: int = 1, text: str = None) → Sticky

Create a sticky note.

Parameters:

• x (int) – x-coordinate of the sticky note (in grid units).

• y (int) – y-coordinate of the sticky note (in grid units).

• text (str) – Content of sticky note.

Returns:

The created sticky note.

Return type:

Sticky

UserCanvas.create_divider(x: int = 1, y: int = 1, *, width=None, height=None) → Divider

Create a divider component.

Parameters:

• x (int) – x-coordinate of the divider (in grid units).

• y (int) – y-coordinate of the divider (in grid units).

• width (int) – horizontal length of the divider, or

• height (int) – vertical height of the divider

Returns:

the divider component

Return type:

Divider

Changed in version 2.1: Added line1 and line2 parameters

UserCanvas.create_file(x: int = 1, y: int = 1, name: str = None, path: str = None) → Component

Create a file link component

Parameters:

• x (int) – x-coordinate of the file link (in grid units).

• y (int) – y-coordinate of the file link (in grid units).

• name (str) – name to display on the file link

• path (str) – path to the linked file

Returns:

the file link component

Return type:

Component

See also

Project.create_resource()

UserCanvas.create_hyper_link(x: int = 1, y: int = 1, name: str = None, hyperlink: str = None) → Component

Create a hyper-link component

Parameters:

• x (int) – x-coordinate of the hyper-link (in grid units).

• y (int) – y-coordinate of the hyper-link (in grid units).

• name (str) – name to display on the hyper-link

• hyperlink (str) – URL to the linked resource

Returns:

the hyper-link component

Return type:

Component

UserCanvas.create_bookmark_link(bookmark, x: int = 1, y: int = 1) → Component

Create a bookmark link, which can be used to navigate to a bookmarked location.

Parameters:

• bookmark – value returned from Project.bookmark()

• x (int) – x-coordinate of the bookmark link (in grid units).

• y (int) – y-coordinate of the bookmark link (in grid units).

Returns:

the bookmark link component

Return type:

Component

Graphs

UserCanvas.create_graph_frame(x: int = 1, y: int = 1) → GraphFrame

Create an empty Graph Frame

Parameters:

• x (int) – X location of the graph frame (in grid units).

• y (int) – Y location of the graph frame (in grid units).

Returns:

The graph frame

Return type:

GraphFrame

UserCanvas.create_graph(pgb: PGB = None, x: int = 1, y: int = 1) → Tuple[GraphFrame, OverlayGraph, Optional[Curve]]

Create an Graph Frame containing an Overlay Graph with a Signal

Parameters:

• pgb (Component) – the PGB for the signal to add to the graph.

• x (int) – X location of the graph frame (in grid units).

• y (int) – Y location of the graph frame (in grid units).

Returns:

The new graph frame, Overlay Graph, and Curve.

Return type:

Tuple[GraphFrame,OverlayGraph,Curve]

UserCanvas.create_polygraph(pgb: PGB = None, x: int = 1, y: int = 1, digital: bool = False) → Tuple[GraphFrame, PolyGraph, Optional[Curve]]

Create an Stacked PolyGraph with a Signal

Parameters:

• pgb (Component) – the PGB for the signal to add to the graph.

• x (int) – X location of the graph frame (in grid units).

• y (int) – Y location of the graph frame (in grid units).

• digital (bool) – Set to True to create a digital polygraph

Returns:

The new graph frame, PolyGraph, and Curve.

Return type:

Tuple[GraphFrame,PolyGraph,Curve]

UserCanvas.create_xy_plot(x: int = 1, y: int = 1, polar: bool = False) → PlotFrame

Create an XY PlotFrame

Parameters:

• x (int) – X location of the plot frame (in grid units).

• y (int) – Y location of the plot frame (in grid units).

• polar (bool) – Set to True to for the polar variant.

Returns:

The plot frame

Return type:

PlotFrame

UserCanvas.create_poly_meter(pgb: Component = None, x: int = 1, y: int = 1) → PolyMeter

Create a polymeter from a PGB component

Parameters:

• pgb (Component) – a PGB component.

• x (int) – X location of the polymeter (in grid units).

• y (int) – Y location of the polymeter (in grid units).

Returns:

the polymeter component.

Return type:

PolyMeter

UserCanvas.create_phasor_meter(pgb: PGB, x: int = 1, y: int = 1, angle: str = None) → PhasorMeter

Create a phasor meter from a PGB component

Parameters:

• pgb (Component) – a PGB component.

• x (int) – X location of the phasor meter (in grid units).

• y (int) – Y location of the phasor meter (in grid units).

• angle (str) – The input angle format "degrees" or "radians"

Returns:

the phasor meter component.

Return type:

PhasorMeter

UserCanvas.create_oscilloscope(pgb: PGB, x: int = 1, y: int = 1) → Oscilloscope

Create an oscilloscope from a PGB component

Parameters:

• pgb (Component) – a PGB component.

• x (int) – X location of the oscilloscope (in grid units).

• y (int) – Y location of the oscilloscope (in grid units).

Returns:

the oscilloscope component.

Return type:

Oscilloscope

Controls

UserCanvas.create_control_frame(x: int = 1, y: int = 1, *control_components: Component) → Tuple[ControlFrame, List[Control]]

Create a control frame

Parameters:

• x (int) – X location of the control frame (in grid units).

• y (int) – Y location of the control frame (in grid units).

Returns:

the control frame & any controls

Return type:

Tuple[ControlFrame,List[Controls]]

Graphics Canvas

class mhi.pscad.GfxCanvas

A graphics canvas is a surface where graphic components can be placed and arranged.

The graphic canvas is accessed with defn.graphics.

New in version 2.2.

create_component(shape: Gfx, extra=None)

Create a new graphic object on a Graphics canvas.

add_port(location, name: str, mode: str, *, dim: int = 1, **kwargs)

Add a port to the component definition.

add_input(location, name: str, dim: int = 1, datatype: str = 'REAL')

Add a control signal input port to the component definition.

add_output(location, name: str, dim: int = 1, datatype: str = 'REAL')

Add a control signal output port to the component definition.

add_electrical(location, name: str, dim: int = 1, electype: str = 'FIXED')

Add an electrical connection port to the component definition.

add_line(p1, p2, *, color: str = 'black', dasharray: str = 'SOLID', thickness: str = '02_PT', port: str = '', cond: str = 'true', arrow_head: Optional[Tuple[int, int]] = None)

Add a line to the component graphics.

add_rectangle(p1, p2, *, color: str = 'black', dasharray: str = 'SOLID', thickness: str = '02_PT', port: str = '', fill_style: str = 'HOLLOW', fill_fg: str = 'black', fill_bg: str = 'black', cond: str = 'true')

Add a rectangle to the component graphics.

add_text(location, text, *, cond: str = 'true', color: str = 'black', anchor: str = 'LEFT', full_font: str = 'Tahoma, 10pt', angle: float = 0.0)

Add a text label to the component graphics.