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

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, mhi.pscad.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.

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.

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

Add an electrical connection 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_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_output(location, name: str, dim: int = 1, datatype: str = 'REAL')

Add a control signal output port to the component definition.

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

Add a port to the component definition.

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.

create_component(shape: mhi.pscad.automation.graphics.Gfx, extra=None)

Create a new graphic object on a Graphics canvas.