Canvas#

class mhi.pscad.Canvas(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

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)

Added in version 2.0.

Canvas.name#: The name of the definition (read-only)

Added in version 2.0.

Canvas.parameters() → Parameters#

Canvas.parameters(parameters: Parameters | None = None, **kwargs) → None

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’

Added in version 2.1.

Canvas.parameter_range(parameter: str) → ParameterRange#: Get legal values for a setting

Added in version 2.1.

Canvas.size#: Canvas size, in grid units

Added in version 2.9.6.

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]

Added in version 2.0.

Canvas.bounds(components: Sequence[Component]) → List[Rect]#

Return a list of the bounds of the given components.

Equivalent to [cmp.bounds for cmp in components] but without the round trip to the server for each component.

Added in version 2.9.6.

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: int) → Component#

Retrieve a component by ID.

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

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

Names In Use#

Canvas.names_in_use(defn: str | None = None, **params) → Set[str]#: Return the set of “Name” parameter values, for all components on the canvas that have a “Name” parameter.

Added in version 3.0.0.

Finding Empty Spaces on Canvas#

Canvas.get_empty_rects(w: int, h: int) → List[Rect]#

Returns empty rectangle spaces on the canvas.

Parameters:

w (int) – Width of the empty rectangles.
h (int) – Height of the empty rectangles.

Returns:

List of empty rectangles.

Return type:

List[Rect]

Added in version 2.9.6.

Canvas.closest_empty_rect(w: int, h: int, point: Tuple[int, int] | Point) → Rect#

Returns an empty rectangle with the size provided, closest to the given point.

Parameters:

w (int) – Width of the empty rectangle.
h (int) – Height of the empty rectangle.
point (Union[Tuple[int, int], Point]) – The point to which the nearest empty rectangle is found.

Returns:

Closest empty rectangle to the given point.

Return type:

Rect

Added in version 2.9.6.

Creating Components#

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

Canvas.create_component(defn: 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.

Added 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.

Added in version 2.0.

Canvas.select_components(x1: int, y1: int, x2: int | None = None, y2: int | None = None, width: int | None = None, height: int | None = 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#

Added 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)

User Canvas#

class mhi.pscad.UserCanvas(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

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')

Definition#

UserCanvas.definition#: The definition which this canvas belongs to.

Added in version 3.0.9.

Parameters#

UserCanvas.parameters() → Parameters#

UserCanvas.parameters(parameters: Parameters | None = None, **kwargs) → None

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

Added in version 2.1.

UserCanvas.parameter_range(parameter: str) → ParameterRange#: Get legal values for a setting

Added 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

Added 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.

Added 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 UserCmp.port() 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 UserCmp.port() 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

Connections#

UserCanvas.create_connection(p1: AnyPoint, p2: AnyPoint) → None#

UserCanvas.create_connection(p1: AnyPoint, p2: AnyPoint, *, label: str, electrical: bool) → str

Creates a connection between two points. If label is not provided (default), the connection is made using wires; otherwise, electrical must be set to True/False to create electrical/data labels to connect points.

Parameters:

p1 (AnyPoint) – One of the two ends of connection
p2 (AnyPoint) – The other end of connection
label (str, optional) – Specifies the node label. A suffix, starting from “_2” is added to label until it is unique on canvas. Defaults to None.
electrical (bool, optional) – Set True, for electrical and False for data node labels. Must be provided if label is specified. Defaults to None.

Returns:

Name of the node labels created if label is provided; otherwise, None.

Return type:

Optional[str]

Added in version 2.9.6.

Changed in version 3.0.2: PSCAD 5.1 requirement is removed.

Annotations#

UserCanvas.create_annotation(x: int = 1, y: int = 1, line1: str | None = None, line2: str | None = 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 = 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: int | None = None, height: int | None = 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_group_box(x: int = 1, y: int = 1, name: str | None = None) → GroupBox#

Create a group box.

Parameters:

x (int) – x-coordinate of the group box (in grid units).
y (int) – y-coordinate of the group box (in grid units).
name (str) – Name (or caption) of group box.

Returns:

The created group box.

Return type:

GroupBox

Added in version 2.9.

UserCanvas.create_file(x: int = 1, y: int = 1, name: str | None = None, path: str | None = 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

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 = None, x: int = 1, y: int = 1) → Tuple[GraphFrame, OverlayGraph, Curve | None]#

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 = None, x: int = 1, y: int = 1, digital: bool = False) → Tuple[GraphFrame, PolyGraph, Curve | None]#

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: PGB | None = 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 = 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(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

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

The graphic canvas is accessed with defn.graphics.

Added in version 2.2.

create_component(shape: Gfx, extra: Gfx | int | None = None)#: Create a new graphic object on a Graphics canvas.

add_port(location: Tuple[int, int], name: str, mode: str, *, dim: int = 1, **kwargs)#: Add a port to the component definition.

add_input(location: Tuple[int, int], name: str, dim: int = 1, datatype: str = 'REAL')#: Add a control signal input port to the component definition.

add_output(location: Tuple[int, int], name: str, dim: int = 1, datatype: str = 'REAL')#: Add a control signal output port to the component definition.

add_electrical(location: Tuple[int, int], name: str, dim: int = 1, electype: str = 'FIXED')#: Add an electrical connection port to the component definition.

add_line(p1: Tuple[int, int], p2: Tuple[int, int], *, color: str = 'black', dasharray: str = 'SOLID', thickness: str = '02_PT', port: str = '', cond: str = 'true', arrow_head: Tuple[int, int] | None = None)#: Add a line to the component graphics.

add_rectangle(p1: Tuple[int, int], p2: Tuple[int, int], *, 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: Tuple[int, int], text: str, *, 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.

Table of Contents

Previous topic

Next topic

Canvas#

Properties#

Finding Components#

Finding By Id#

Names In Use#

Finding Empty Spaces on Canvas#

Creating Components#

Clipboard Operations#

Transformations#

Navigation#

User Canvas#

Definition#

Parameters#

Smart Clipboard#

Composition#

Creating …#

Wires#

Connections#

Annotations#

Graphs#

Controls#

Graphics Canvas#