Canvas & Components

User Canvas

class mhrc.automation.usercanvas.UserCanvas(project, name, *iid)

User Canvas

A canvas is a surface when 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, which permit only certain types of components.)

The main page of a project is typically retrieved with:

main = project.user_canvas('Main')

Finding Components

The find(), find_first() and 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.

UserCanvas.find([[definition,] 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 components match the given criteria.

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)
  • 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:

A component controller object for the found component, or None if no matching component can be found.
Raises:

ValueError – if more than 1 components match the criteria.

Examples:

c = find('Bus'                # the one and only Bus component
c = find('Bus10')             # the component named "Bus10"
c = find('Bus', 'Bus10')      # the Bus component named "Bus10"
c = find('Bus', BaseKV='138') # the Bus with BaseKV="138"
c = find(BaseKV='138')        # the only component with BaseKV="138"
UserCanvas.find_first([[definition,] name,] [key=value, ...])

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

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)
  • 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:

A component controller object for the found component, or None if no matching component can be found.

Examples:

c = find_first('Bus'                # a Bus component
c = find_first('Bus10')             # a named "Bus10"
c = find_first('Bus', 'Bus10')      # a Bus component named "Bus10"
c = find_first('Bus', BaseKV='138') # a Bus with BaseKV="138"
c = find_first(BaseKV='138')        # a component with BaseKV="138"
UserCanvas.find_all([[definition,] name,] [key=value, ...])

Find all component that matches 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)
  • 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:

A list of component controller objects for the matching components. If no matching components can be found, an empty list is returned.

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"

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.

UserCanvas.user_cmp(iid)

Retrieve by its Id attribute a controller for a user component.

Note

A “user component” is the term used to describe a component which is not built-in to the PSCAD application, but rather has a definition which is read from a component library. In this sense, most components in the “Master Library” are user components.

A user component may be identified by a colon (:) in the definition name.

Parameters:iid (int) – The Id attribute of the user component.
Returns:A user component proxy object.
UserCanvas.bus(iid)

Retrieve by its Id attribute a controller for a Bus.

Parameters:iid (int) – The Id attribute of the Bus.
Returns:A Bus proxy object.
UserCanvas.tline(iid, defn=None)

Retrieve by its Id attribute a controller for a T-Line.

Parameters:iid (int) – The Id attribute of the T-Line.
Returns:A T-Line proxy object.
UserCanvas.cable(iid, defn=None)

Retrieve by its Id attribute a controller for a Cable.

Parameters:iid (int) – The Id attribute of the Cable.
Returns:A Cable proxy object.
UserCanvas.graph_frame(iid)

Retrieve by its Id attribute a controller for a Graph Frame.

Parameters:iid (int) – The Id attribute of the Graph Frame.
Returns:A Graph Frame proxy object.
UserCanvas.overlay_graph(frame_id, id)

Retrieve by its Id attribute a controller for an Overlay Graph.

Parameters:
  • frame_id (int) – The Id attribute of the Graph Frame.
  • id (int) – The Id attribute of the Overlay Graph.
Returns:

An Overlay Graph proxy object.
UserCanvas.slider(frame_id, id)

Retrieve by its Id attribute a controller for a Slider, nested in a control frame.

Parameters:
  • frame_id (int) – The Id attribute of the Control Frame.
  • id (int) – The Id attribute of the Slider.
Returns:

A Slider proxy object.
UserCanvas.switch(frame_id, id)

Retrieve by its Id attribute a controller for a Switch, nested in a control frame.

Parameters:
  • frame_id (int) – The Id attribute of the Control Frame.
  • id (int) – The Id attribute of the Switch.
Returns:

A Switch proxy object.
UserCanvas.button(frame_id, id)

Retrieve by its Id attribute a controller for a Button, nested in a control frame.

Parameters:
  • frame_id (int) – The Id attribute of the Control Frame.
  • id (int) – The Id attribute of the Button.
Returns:

A Button proxy object.
UserCanvas.selector(*iid)

button(frame_id, id) Retrieve by its Id attribute a controller for a Selector, nested in a control frame.

Parameters:
  • frame_id (int) – The Id attribute of the Control Frame.
  • id (int) – The Id attribute of the Selector.
Returns:

A Selector proxy object.
UserCanvas.list_components()

List all components on canvas.

Returns:An XML fragment containing the the contents of the canvas.

For a friendlier way of getting the entire canvas contents, use:

contents = canvas.find_all()

Creating Components

UserCanvas.add_component(library, name, x=0, y=0)

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 on the canvas for the component.
  • y (int) – Y location on the canvas for the component.
Returns:

The created UserComponent.
UserCanvas.add_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.

Returns:A created Wire.

Note

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

Clipboard Operations

UserCanvas.select_components(x1, y1, x2=None, y2=None, width=None, height=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)
UserCanvas.clear_selection()

Reset the selection so that no components are selected.

UserCanvas.copy()

Copy the currently selected components to the clipboard.

UserCanvas.cut()

Cut the currently selected components to the clipboard.

UserCanvas.paste()

Paste the contents of the clipboard into this canvas

UserCanvas.delete()

Delete the currently selected components.

UserCanvas.paste_transfer()

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

See:
UserComponent.copy_transfer()

User Component

class mhrc.automation.usercmp.UserComponent(canvas, iid)

User Component Command Object

Location

UserComponent.set_location(x, y)

Set the component’s (x,y) location

Parameters:
  • x (int) – The new x location for this component
  • y (int) – The new y location for this component
UserComponent.get_location()

Get this component’s (x,y) location

Returns:The x,y location of the component.
Return type:tuple(int,int)
UserComponent.get_port_location(name)

Based on the location and any rotation and/or mirroring of this component, return the location of the named port.

Parameters:name (str) – Name of port
Returns:Location (x,y) of the port, or None if the port is not enabled or does not exist.

Properties

UserComponent.set_parameters([scenario, ]name=value[, ...])

Set the component parameters.

The valid parameters for the component are determined by the component definition.

Parameters:
  • scenario (str) – Name of scenario to set parameters for. (optional)
  • **kwargs – One or more name=value keyword parameters
UserComponent.get_parameters(scenario=None)

Get the component parameters.

The parameters contained in the component are determined by the component definition.

Parameters:scenario (str) – Name of scenario to get parameters from. (optional)
Returns:A dictionary of property name=value pairs.
UserComponent.view_ParameterGrid()

View the parameter grid for this component

Modules

UserComponent.get_definition()

Retrieve a controller for this component definition.

Returns:A definition controller proxy object.
UserComponent.is_module()

Check to see if this component has its own canvas, with in turn, can contain additional components.

Returns:True if the component has an internal canvas, False otherwise.
UserComponent.navigate_in()

Navigate into a page module or definition

Layers

UserComponent.add_to_layer(name)

Add this component to the given layer.

The layer must exist, but need not be enabled or visible.

Parameters:name (str) – The layer to add the component to.
UserComponent.remove_from_layer(name)

Remove this component from the given layer.

The layer must exist, but need not be enabled or visible.

Parameters:name (str) – The layer to remove the component from.

Clipboard

UserComponent.copy()

Copy this component to the clipboard.

UserComponent.cut()

Cut this component to the clipboard

UserComponent.delete()

Delete this component.

UserComponent.copy_transfer()

Copy the component as well as its definition to the clipboard, so it can be used in another project.

See:
UserCanvas.paste_transfer()

Component Definition

class mhrc.automation.definition.Definition

A Component Definition

All User Components have a component definition, which specifies what parameters the component has, and whether or not the component is a module, with its own canvas containing other components.

scope

Project the definition is defined in

name

Name of the definition

scoped_name

The scoped definition name is the project and definition names, separated by a colon.

is_module()

Check to see if this definition is a module.

A module will have a canvas, which can contain other components.