The parameter options for this call are identical to DWCircuit.signals except that only bundles are returned
Method: addDevice
Adds a device to the circuit (i.e. places it on the diagram)
DWDevice addDevice(type);
DWDevice addDevice(type, posX, posY);
DWDevice addDevice(type, posX, posY, orient);
DWDevice addDevice(type, posX, posY, orient, page);
DWDevice addDevice(type, posX, posY, orient, page, hitTest);
DWDevice addDevice(libName, partName);
DWDevice addDevice(libName, partName, posX, posY);
DWDevice addDevice(libName, partName, posX, posY, orient);
DWDevice addDevice(libName, partName, posX, posY, orient, page);
DWDevice addDevice(libName, partName, posX, posY, orient, page, hitTest);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| partName | String | The part name of the desired item in the library |
| orient | char | A character specifying the orientation of the device, see below, defaults to E |
| libName | String | A string uniquely identifying a currently open library, usually the file name |
| page | integer | The destination page for the device in the range 1..#pages, defaults to 1 |
| hitTest | boolean | Specifies whether the pin connection points on the device should be checked for connection to existing signals in the circuit, defaults to false. |
| type | DWType | A DWType object representing the part type to be instantiated |
| posY | integer | The Y position of the top left corner of the device, in 1/1000", defaults to 0. If this circuit is to be viewed and edited later, then this value should be a multiple of the grid spacing of 70 units. |
| posX | integer | The X position of the top left corner of the device, in 1/1000", defaults to 0. If this circuit is to be viewed and edited later, then this value should be a multiple of the grid spacing of 70 units. |
Returns a DWDevice object representing the new device
The first style of call is intended for making invisible circuits and will place the device in the center of the page in standard orientation. The other parameters allow the position and orientation of the device to be specified.
The orientation parameter can be one of the following: E=East, e=East-flipped, W=West, w=West-flipped, N=North, n=North-flipped, S=South, s=South-flipped.
It is the caller's responsibility to ensure that the X and Y coordinates provided adhere to the grid requirements of the circuit. This normally means that they must be a multiple of 70.
Method: addGraphic
Adds a graphic item to the circuit (i.e. places it on the diagram)
void addGraphic(pic, posX, posY);
void addGraphic(pic, posX, posY, page);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| pic | DWPic | A DWPic object containing the graphic items to be added to the schematic. If the picture object contains exactly one primitive element (e.g. a line) then it is added as is. If there are more than one element, they are added as a group. |
| page | integer | The destination page for the graphic in the range 1..#pages, defaults to 1 \ |
| posY | integer | The Y position of the top left corner of the graphic, in 1/1000". |
| posX | integer | The X position of the top left corner of the graphic, in 1/1000". |
None
Method: addPage
Adds one more page to the circuit
DWPage addPage();
DWPage addPage(visible);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| visible | bool | Specifies whether the new page should be opened (made visible). Defaults to false if not specified |
DWPage object representing the new page
Method: addPortConn
Adds a device to the circuit (i.e. places it on the diagram) so that it is positioned adjacent to and connects to the given existing pin in the circuit. This is primarily intended for automatically adding port connector devices to a subcircuit but nothing restricts the device type to being a port connector.
DWDevice addPortConn(type, pin);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| pin | DWPin | A DWPin object representing the pin to connect to |
| type | DWType | A DWType object representing the part type to be instantiated |
Returns a DWDevice object representing the new device
The device being placed is assumed to have one visible pin and is rotated and positioned so that this pin connects to the given pin.
Method: addSignal
Adds a signal to the circuit.
DWSignal addSignal();
DWSignal addSignal(page);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| page | integer | The destination page for the signal in the range 1..#pages, defaults to 1 |
Returns a DWSignal object representing the new signal
The signal will initially be invisible until pin connections and lines are attached to it.
It is not normally necessary to use this call to create a signal. Every time a device is added, signals are already created for each pin, so simply connecting pins together will result in signal structures existing as needed. This method can be used if a signal with no connections is needed or if data order makes it simpler to create and name signals before connecting devices to them.
Property: allInstances
Gets a string array containing the instance locators for all possible physical instances of this object
SPArray allInstances();
Property: attributeList
Gets or sets the attribute list (i.e. the collection of all attribute values) associated with this object.
SPArray attributeList();
attributeList = SPArray
Returns or accepts an SPArray of DWAttribute objects
Method: bundles
Retrieves an array of bundles (represented by (DWSignal) objects) for the circuit with various filtering options.
The parameter options for this call are identical to DWCircuit.signals except that only bundles are returned
Property: changed
Gets or sets the "changed" status of the circuit. If the circuit is marked as changed, a close by the user will prompt for a save, otherwise it will just close immediately.
bool changed();
changed = bool
Method: clear
Deletes the selected objects in the circuit. This is equivalent to the Clear menu command.
void clear();
Method: close
Closes the design associated with this circuit with or without prompting the user.
void close();
void close(force);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| force | bool | true to close the design without saving or prompting the user. |
If this method is called with no argument or with force=false, this is equivalent to selecting the Close Design command. With force=true, the design is closed immediately with no prompt and no save.
Method: copy
Copies the selected objects in the circuit to the system clipboard or to a given circuit.
void copy();
void copy(destCct);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| destCct | DWCircuit | The destination circuit for the copy. The circuit is cleared (i.e. all existing objects deleted) before the copy. If this argument is provided, the system clipboard is not affected by this operation. If the argument is not given, this method is equivalent to the Copy menu command. |
Method: cut
Copies the selected objects in the circuit to the system clipboard or to a given circuit, then deletes the selected objects from the source circuit.
void cut();
void cut(destCct);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| destCct | DWCircuit | The destination circuit for the copy. The circuit is cleared (i.e. all existing objects deleted) before the copy. If this argument is provided, the system clipboard is not affected by this operation. If the argument is not given, this method is equivalent to the Cut menu command. |
Method: defineAttribute
Defines or modifies the definition of an attribute field in the design associated with this circuit
int defineAttribute(fieldName, options);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| fieldName | String | Name of the field to define, must meet the rules for a valid name |
| options | String | String containing letters corresponding to field options (see below) and an optional length limit. This value cannot be empty and must define at least one of the allowed object types |
Returns the internal field number (1..N) for the defined or modified field, or 0 if any error
This table defines the available options.
| Letter | Description |
| A | Allow carriage return |
| C | Defined for design |
| D | Defined for devices |
| F | Fixed field (cannot be removed once defined, usually only used for fields required for internal operation) |
| G | Group with Name field |
| L | Location fixed, cannot be repositioned by the user |
| M | Temporary field, value is not saved to file |
| N | Only valid name characters allowed in value (this is not enforced in this version) |
| P | Defined for pins |
| R | Rotate with the device |
| S | Defined for signals |
| U | Only valid numeric characters allowed in value (this is not enforced in this version) |
| V | Make value visible by default (other settings in the program affect visibility and may override this setting) |
| W | Show field name with value by default |
| X | Value fixed, cannot be edited by the user |
| Y | Primary field, will be displayed when "Primary Only" is selected |
The flag letters may be optionally followed by an integer specifying the maximum value length. This length is not enforced in the program and is only used to determine the type of box displayed when prompting for a value.
NOTE: This method can be called on any circuit or subcircuit in a design, but the attribute definitions apply to the entire design
EXAMPLE: The string
DY32
will specify a primary field, valid for devices, with maximum value length of 32
Method: deselectAll
Deselects all objects on the given page of this circuit, as if the user had clicked the mouse in an unused area of the diagram.
void deselectAll();
void deselectAll(pageNum);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| pageNum | int | The page number (1..N) containing the objects to deselect. If this is not specified, then the current page is used, or, if no current page, page 1 is used. |
Property: design
Gets the design containing this circuit, may be itself if this is a top-level circuit. Read-only
DWCircuit design();
Method: devices
Retrieves an array of device objects for the circuit with various filtering options.
SPArray = devices
SPArray = devices(tokenList);
SPArray = devices(fieldName, value, ...);
SPArray = devices(fieldName, regExp, ...);
SPArray = devices(options, fieldName, value, ...);
SPArray = devices(options, fieldName, regExp, ...);
SPArray = devices(options, restrict, fieldName, value, ...);
SPArray = devices(options, restrict, fieldName, regExp, ...);
SPArray = devices(options, restrict, scope, fieldName, value, ...);
SPArray = devices(options, restrict, scope, fieldName, regExp, ...);
SPArray = devices(options);
SPArray = devices(options, restrict);
SPArray = devices(options, restrict, scope);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| scope | int | This is used in hierarchical designs to determine how much of the hierarchy is extracted. This can be exactly one of the following values:
|
| regExp | RegExp | A regular expression that will be applied to the preceding attribute field. If the expression matches, the device is included in the list. |
| value | String | The value of the preceding attribute field that must be matched exactly for the device to be included in the list. |
| fieldName | String | The name of an attribute field. The following parameter can be a string value, which must be exactly equal for the device to be included, or can be a regular expression. Any number of fieldName/value or fieldName/regExp pairs can be specified. |
| options | int | This is a set of flags that allows you to filter the list to include/exclude various categories of devices. This argument can be any OR of the following values:
|
| tokenList | String | A comma-separated list of token numbers of devices |
| restrict | int | This selects a bit in the Restrict attribute field that will be used to exclude certain devices. This can be exactly one of the following:
|
Returns an SPArray object containing a list of all devices(DWDevice) specified by the option parameters.
Returns an array with one element for each device requested. All devices on all pages of this circuit are included. If you only want a specific page, use DWPage.devices.
If no parameters are specified, you will get a list of all the devices on all pages of the given circuit, excluding pseudo-devices such as bus breakouts and page connectors.
A variety of different combinations of parameters can be passed, and the meaning of each is determined by the data type of the parameter. If the first one, two or three parameters are integers, then they are interpreted as the options, restrict and scope parameters, respectively. Once any non-integer (normally a string) parameter is encountered, this is assumed to be an attribute value filter, as follows
Any remaining parameters are taken as attribute field name/value or field name/regular expression pairs. Any devices matching the given values or patterns will be included in the list.
Note that this array is not updated automatically. If you perform other operations that add or delete devices, this array will be invalid and should be retrieved again. This can cause the program to bomb if misused!
cct = currentCircuit();
devs = cct.devices(); // All the non-pseudo-devices in the circuit
devs = cct.devices("Part", "RES", "Name", /R1.+/); // All devices with Part field equal to "RES" and Name matching the given expression
devs = cct.devices(1); // All selected devices in the circuit
Property: fileAppVersion
An integer indicating the program version that created the associated design file. Read only.
int fileAppVersion();
NOTE: The returned value is a 20-bit binary integer which can be interpreted as 5 hex digits.
Property: fileDir
The directory path of the file associated with this circuit, i.e. the name of the directory containing the file. Read only.
String fileDir();
Property: fileFormatVersion
An integer indicating the format version of the associated design file. Read only.
int fileFormatVersion();
NOTE: This number specifies the format of the file and is changed only when non backward-compatible changes are made to the format. It is not necessarily changed when the program version number changes. The format number was changed to 6 for EMTPWorks 4.0 as a result of a number of file format changes to accommodate Unicode strings, and other changes.
Property: fileName
The name of the file associated with this circuit, i.e. the file name without any directory path. Read only.
String fileName();
Property: filePath
The full directory path and file name of the file associated with this circuit. Read only.
String filePath();
Method: findByLocator
Searches the design containing this circuit for an object (circuit, device, signal or pin) that matches the given locator string.
object findByLocator(loc);
object findByLocator(loc, rel);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| loc | String | The locator string |
| rel | boolean | true to search relative to this circuit, false to search relative to the root of the design containing this circuit. false by default |
Returns a DWDevice, DWSignal, DWCircuit or DWPin object representing the object found or null if no match.
A locator string has encoded in it the type of object it specifies, so this method will return that type of object. You can use the "objType" method to determine what type of object you have received.
Method: findObjectByName
Searches given circuit for an ActiveX object with the given name. This gives direct access to the objects properties and methods.
object findObjectByName(name);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| name | String | The name of the object |
Returns a direct interface to the object or null if no match.
If there are multiple objects with the same name, the first one found will be returned.
Property: frame
Gets the bouding frame for the given page of this circuit
DWRect = frame
DWRect = frame(pageNum);
DWRect = frame(pageNum, selectedOnly);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| selectedOnly | Boolean | True to frame only the selected objects in the circuit, defaults to false. |
| pageNum | int | The page number to retrieve the frame for. Defaults to 1 if not supplied. |
Method: getAttribute
Gets an attribute value from this object
String getAttribute(fieldName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| fieldName | String | The name of the field to retrieve |
Returns a string representing the value of the specified attribute field. This string will be empty (zero length) if the field does not exist.
Method: getAttributeDefinition
Returns the internal field number, option flags and maximum value length for the field
String getAttributeDefinition(fieldName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| fieldName | String | Name of the field to query |
Returns the option string, described below. Returns an empty string if there is no definition for the given name
See defineAttribute for the flag letters used to specify field options. The returned option string consists of:
NOTE: This method can be called on any circuit or subcircuit in a design, but the attribute definitions apply to the entire design
Method: getAttributeFieldNames
Returns an array of field names matching the given option flags
SPArray getAttributeFieldNames(options);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| options | String | Option flags. This can contain any combination of the flag characters given below. Any flag in this value must match the corresponding bit in the field definition to select the field |
Returns an array of names
This table defines the available options.
| Flag | Description |
| C | Defined for circuit (design) |
| D | Defined for devices |
| P | Defined for pins |
| S | Defined for signals |
| Y | Primary field, will be displayed when "Primary Only" is selected |
Method: getAttributeVis
Gets the visibility of an attribute on this object
bool getAttributeVis(fieldName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| fieldName | String | The name of the field to retrieve |
Returns true if the field is displayed on the schematic, false otherwise
Method: getCircuitLocatorByName
Returns the locator of a circuit given a hierarchical name.
object getCircuitLocatorByName(name);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| name | String | The name to search for |
Returns a string containing the locator name of the circuit, or null if not found.
NOTES:
Method: getDefaultDeviceName
Returns the next unused name having the given prefix. The prefix can be either given explicitly, derived from a given device or type or obtained from the design's default settings
String getDefaultDeviceName();
String getDefaultDeviceName(prefix);
String getDefaultDeviceName(device);
String getDefaultDeviceName(type);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| prefix | String | The prefix to use in generating the name |
| device | DWDevice | A device object which will be checked for a prefix attribute |
| type | DWType | A tyype object that will be checked for prefix attributes |
In all cases, the default settings are the final resort, i.e. if no prefix is provided or if the given object has no prefix attributes, the settings from the design or default application settings will be used
Method: getDefaultSignalName
Returns the next unused name having the given prefix. The prefix can be either given explicitlyor obtained from the design's default settings
String getDefaultSignalName();
String getDefaultSignalName(prefix);
String getDefaultSignalName(doBus3);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| doBus3 | bool | pass true to use the default prefix for 3-phase bus signals, otherwise the default prefix for general signals is used |
| prefix | String | The prefix to use in generating the name |
In all cases, the default settings are the final resort, i.e. if no prefix is provided the settings from the design or default application settings will be used
Method: getDeviceLocatorByName
Returns the locator of a device given a hierarchical name.
object getDeviceLocatorByName(name);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| name | String | The name to search for |
Returns a string containing the locator of the device, or null if not found.
NOTES:
Method: getLineStyle
Creates a new line style or gets an existing line style associated with this design
DWLineStyle = getLineStyle(name, detach);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| detach | bool | If true, a clone of the specified line style is created but with a new name and GUID assigned so that changes will not affect other objects using this style. If false, this object will refer directly to the identified style definition and changes will affect any other users of this style. Defaults to false |
| name | String | The name or GUID of the desired line style. If this is not specified, a new, empty line style is created |
Method: getNameByLocator
Returns the hierarchical name of the object that matches the given locator string.
object getNameByLocator(loc);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| loc | String | The locator string |
Returns a string containing the hierarchical name of the object, or null if not found.
NOTES:
Property: getProperties
Gets a properties object associated with this object.
Property: getProperty
Gets a named property associated with this object.
Method: getSignalLocatorByName
Returns the locator of a signal given a hierarchical name.
object getSignalLocatorByName(name);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| name | String | The name to search for |
Returns a string containing the locator of the signal, or null if not found.
NOTES:
Property: instanceHierName
Gets or sets the selected physical instance of the circuit using its hierarchical name to identify it
String instanceHierName();
instanceHierName = String
The instance locator string identifies the currently selected unique physical instance of an object within a hierarchical circuit structure. Setting the instance locator does not change the locator of the definition object, it only selects one of the possible physical instances that can be represented by this definition. If the given instance locator is not valid for this definition, it is ignored. If it is valid and is different than the current selected instance and if the instance is in a displayed circuit, the display will be updated to reflect the change.
Property: instanceLocator
Gets or sets the selected physical instance of the circuit using its locator to identify it
String instanceLocator();
instanceLocator = String
The instance locator string identifies the currently selected unique physical instance of this object within a hierarchical circuit structure. Setting the instance locator does not change the locator of the definition object, it only selects one of the possible physical instances that can be represented by this definition. If the given instance locator is not valid for this definition, it is ignored. If it is valid and is different than the current selected instance and if the instance is in a displayed circuit, the display will be updated to reflect the change.
Property: isLocked
Gets the "locked" status of the circuit, i.e. whether it can be opened by the user.
bool isLocked();
This property is read-only
Property: isOpen
Returns true if this circuit is open (i.e. it is still in memory and any window is open), false if it has been closed
bool isOpen();
Property: isPhysical
Gets or sets the "physical" hierarchy mode of the design
bool isPhysical();
isPhysical = bool
Property: isReadOnly
Gets or sets the "read-only" status of the circuit
bool isReadOnly();
isReadOnly = bool
Method: locateDevices
Retrieves an array of device objects for the circuit with various filtering options.
SPArray = locateDevices
SPArray = locateDevices(baseLocator);
SPArray = locateDevices(baseLocator, fieldName, value, ...);
SPArray = locateDevices(baseLocator, fieldName, regExp, ...);
SPArray = locateDevices(baseLocator, options, fieldName, value, ...);
SPArray = locateDevices(baseLocator, options, fieldName, regExp, ...);
SPArray = locateDevices(baseLocator, options);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| regExp | RegExp | A regular expression that will be applied to the preceding attribute field. If the expression matches, the device is included in the list. |
| value | String | The value of the preceding attribute field that must be matched exactly for the device to be included in the list. |
| fieldName | String | The name of an attribute field. The following parameter can be a string value, which must be exactly equal for the device to be included, or can be a regular expression. Any number of fieldName/value or fieldName/regExp pairs can be specified. |
| baseLocator | String | The locator string of the circuit to be scanned, or its parent device. If this is empty or not specified, this circuit is scanned and the returned locators will be relative to this circuit. Note that this parameter serves two purposes, it locates the base circuit to use for the scan, and it is also the prefix for all returned locators. If it is absolute (starts with a "/" character) then the scan and the returned locators are relative to the top level of the design regardless of whether this circuit object is the top level. |
| options | int | This is a set of flags that allows you to filter the list to include/exclude various categories of devices. This argument can be any OR of the following values:
|
Returns an SPArray object containing the locators of all devices matching the option parameters.
Returns an array with one element for each device requested. All devices on all pages of this circuit are included.
If no parameters are specified, you will get a list of all the devices on all pages of the given circuit, excluding pseudo-devices such as bus breakouts and page connectors.
A variety of different combinations of parameters can be passed, and the meaning of each is determined by the data type of the parameter. If the first one, two or three parameters are integers, then they are interpreted as the options and restrict parameters, respectively. Once any non-integer (normally a string) parameter is encountered, this is assumed to be an attribute value filter, as follows
Any remaining parameters are taken as attribute field name/value or field name/regular expression pairs. Any devices matching the given values or patterns will be included in the list.
cct = currentCircuit();
devs = cct.locateDevices(); // All the non-pseudo-devices in the current circuit
devs = cct.locateDevices(baseLoc); // All the non-pseudo-devices in the circuit specified by the given locator
devs = cct.locateDevices("", "Part", "RES", "Name", /R1.+/); // All devices with Part field equal to "RES" and Name matching the given expression
devs = cct.locateDevices("", 1); // All selected devices in the circuit
Property: locator
Gets the locator string of the circuit
String locator();
The locator string identifies an object within a hierarchical circuit structure and provides a unique way of identifying this object despite duplicate or non-existant names.
Property: name
Gets the name of the circuit, i.e. the name of the file it is saved in.
String name();
This is a read-only property.
Property: objType
Returns a string with the name of this object class "DWCircuit".
String = objType
Method: open
Opens a window on the circuit, or just brings an existing window to the front if it is already open.
void open();
Property: pages
Retrieves an array of page objects for the circuit
SPArray = pages
Returns an SPArray object containing a list of all pages in this circuit
Returns an array with one element for each page in this circuit, whether or not the pages are open. Note that this array is not updated automatically. If you perform other operations that add or delete pages, this array will be invalid and should be retrieved again.
Property: parentDevice
Gets the parent device of this circuit, if it is a subcircuit, or null if this is a top-level circuit. Read-only.
DWDevice parentDevice();
DWDevice object representing the parent device of this subcircuit
The value of this property will depend on the hierarchy mode of the design and may depend on whether the subcircuit is open for editing. If the design is in physical hierarchy mode and the current circuit is a physical instance circuit (i.e. not a definition circuit), this will be the parent device of the given physical subcircuit instance. In pure mode designs, this property has no conceptual meaning (since a given subcircuit may have many parents), but is set to a specific value to track the order in which the user has opened subcircuits.
Property: parentType
Gets the parent device type of this circuit, if it is a subcircuit, or null if this is a top-level circuit. Read-only.
DWType parentType();
DWType object representing the parent type of this subcircuit
Method: paste
Copies the contents of the system clipboard or a given source circuit to this circuit.
void paste();
void paste(srcCct);
void paste(srcCct, dstPage);
void paste(srcCct, dstPage, posX, posY);
void paste(srcCct, dstPage, posX, posY, orientation);
void paste(srcCct, dstPage, posX, posY, orientation, hitTest);
void paste(srcCct, dstPage, posX, posY, orientation, hitTest, replace);
void paste(srcCct, dstPage, posX, posY, orientation, hitTest, replace, returnOptions);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| srcCct | DWCircuit | The source circuit for the paste. If the argument is not given or is null, this method is equivalent to the Paste menu command and all other arguments are ignored. |
| returnOptions | int | Allows the caller to request that the method return a list of the objects created. The possible values are 0 => no return value (the default), 1 => return an array of the devices created, 2 => return an array of the signals created, 3 => return an array containing both devices and signals (these may be intermixed in any order). Note that if hit testing is enabled, the number of signals returned may not be equal to the number in the source circuit as only newly-created signals are returned |
| orientation | char | A character specifying the orientation of the paste, one of the following: E=East, e=East-flipped, W=West, w=West-flipped, N=North, n=North-flipped, S=South, s=South-flipped., defaults to E |
| dstPage | int | The destination page for the paste. If this is <= 0, the current page is used. |
| hitTest | boolean | Specifies whether the loose connection points on the pasted circuit should be checked for connection to existing signals in the destination circuit, defaults to false. |
| replace | boolean | When true, indicates that the pasted objects are replacing objects that were just removed from the same circuit, e.g. for a move or rotate operation. In this case, the replaced objects retain their original token numbers, making Undo operations more consistent. If this is false, all objects are assigned new token numbers. Defaults to false. |
| posY | int | The horizontal position for the paste, in circuit coordinates |
| posX | int | The horizontal position for the paste, in circuit coordinates. If these are not specified, the objects are pasted at 0,0, the center of the page. |
Method: pins
Retrieves an array of pin objects for the circuit with various filtering options.
SPArray = pins
SPArray = pins(fieldName, value, ...);
SPArray = pins(fieldName, regExp, ...);
SPArray = pins(options, fieldName, value, ...);
SPArray = pins(options, fieldName, regExp, ...);
SPArray = pins(options, restrict, fieldName, value, ...);
SPArray = pins(options, restrict, fieldName, regExp, ...);
SPArray = pins(options, restrict, scope, fieldName, value, ...);
SPArray = pins(options, restrict, scope, fieldName, regExp, ...);
SPArray = pins(options);
SPArray = pins(options, restrict);
SPArray = pins(options, restrict, scope);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| scope | int | This is used in hierarchical designs to determine how much of the hierarchy is extracted. This can be exactly one of the following values:
|
| regExp | RegExp | A regular expression that will be applied to the preceding attribute field. If the expression matches, the device is included in the list. |
| value | String | The value of the preceding attribute field that must be matched exactly for the device to be included in the list. |
| fieldName | String | The name of an attribute field. The following parameter can be a string value, which must be exactly equal for the device to be included, or can be a regular expression. Any number of fieldName/value or fieldName/regExp pairs can be specified. |
| options | int | This is a set of flags that allows you to filter the list to include/exclude various categories of devices. This argument can be any OR of the following values:
|
| restrict | int | This selects a bit in the Restrict attribute field that will be used to exclude certain devices. This can be exactly one of the following:
|
Returns an SPArray object containing a list of all pins (DWPin) specified by the option parameters.
Returns an array with one element for each pin requested. All pins on all devices on all pages of this circuit are included.
If no parameters are specified, you will get a list of all the pins on all pages of the given circuit, excluding pins on pseudo-devices such as bus breakouts and page connectors.
A variety of different combinations of parameters can be passed, and the meaning of each is determined by the data type of the parameter. If the first one, two or three parameters are integers, then they are interpreted as the options, restrict and scope parameters, respectively. Once any non-integer (normally a string) parameter is encountered, this is assumed to be an attribute value filter, as follows
Any remaining parameters are taken as attribute field name/value or field name/regular expression pairs. Any pins matching the given values or patterns will be included in the list.
Note that this array is not updated automatically. If you perform other operations that add or delete devices, this array will be invalid and should be retrieved again. This can cause the program to bomb if misused!
cct = currentCircuit();
ps = cct.pins(); // All the pins on non-pseudo-devices in the circuit
ps = cct.pins("PinFunc", "OUTFUNC"); // All pins with PinFunc field equal to "OUTFUNC"
ps = cct.pins(1); // All selected pins in the circuit
Property: readOnly
Returns true if the circuit is marked "read only". Note that this status primarily affects the user interface and does not prevent script methods from making changes to the circuit.
bool = readOnly
Method: redo
Performs a redo operation, exactly as if the Redo menu command was selected by the user.
void redo();
Property: redraw
Force a redraw of the circuit window
void redraw();
void redraw(redrawAll);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| redrawAll | bool | If true, all open windows on this circuit will be redrawn, if false only the current (topmost) circuit window is redrawn. Default is false |
Method: save
Saves the design associated with this circuit, as if the user had selected the Save command.
bool save();
Returns a boolean value true if the save succeeded, false if it failed or was cancelled by the user in response to a prompt.
Method: saveAs
Saves the design associated with this circuit to a file. The file can be specified directly or by prompting the user.
bool saveAs();
bool saveAs(filePath);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | The directory path and file name of the desired destination file. An absolute path should be provided since there are no guarantees what the current directory will be at the time of the save. |
Returns a boolean value true if the save succeeded, false if it failed or was cancelled by the user in response to a prompt.
When called with no argument, this method is equivalent to the user selecting the "Save As" file menu item. When called with a file path, the design is saved to the given path as if the user had done as Save As to that location.
Method: saveCopy
Saves the design associated with this circuit to a specified file. The design's name, file path, modified dates and save status are not affected by this call so the design is not associated with the saved file in any way.
bool saveCopy(filePath);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | The directory path and file name of the desired destination file. An absolute path should be provided since there are no guarantees what the current directory will be at the time of the save. |
Returns a boolean value true if the save succeeded, false if it failed or was cancelled by the user in response to a prompt.
Property: saved
Gets the "saved" status of the design, i.e. if the design was read from or has been saved to a file. Read only.
bool saved();
This property says only whether the design has ever been saved to a file, it doesn't tell you whether the design has been modified since it was last saved. See changed
Method: select
Makes this circuit current by bringing one of its windows to the front
void select();
Method: selectAll
Deselects all objects on the given page of this circuit, as if the user had clicked the mouse in an unused area of the diagram.
void selectAll();
void selectAll(pageNum);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| pageNum | int | The page number (1..N) containing the objects to select. If this is not specified, then the current page is used, or, if no current page, page 1 is used. |
Method: selectedObjectsProperties
Gets or sets the merged values of all selected objects in this circuit.
DWSchemaObject = selectedObjectsProperties
selectedObjectsProperties = DWSchemaObject
Method: setAttribute
Sets an attribute value in this object
void setAttribute(fieldName, value);
void setAttribute(fieldName, value, visibility);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| value | String | The new value for the specified field |
| fieldName | String | The name of the field to set |
| visibility | int | How to set visibility of resulting attribute text. 0 (false) = hide, 1 (true) = show, 2 = use default setting in design's attribute table, -1 = leave current visibility If this parameter is not supplied, 2 is assumed. |
Null.
If the given field name is not defined in the design's attribute table, it is added automatically. It is preferable to ensure that any fields used are already defined in the target design to make sure the settings are appropriate.
Method: setAttributeDefaultVis
Sets the default visibility for the named attribute field for objects created in this design.
void setAttributeDefaultVis(fieldName, vis);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| fieldName | String | The name of the field to set |
| vis | int | The desired new visibility setting. This can be false (or zero) meaning never visible, true (or 1) meaning always visible, or 2 meaning use the object's own default setting. |
Property: setProperty
Sets a named property associated with this object.
Method: showByLocator
Searches the design containing this circuit for an object (circuit, device, signal or pin) that matches the given locator string.
void showByLocator(loc, flags);
void showByLocator(loc);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| loc | String | The locator string |
| flags | int | any combination of: cFBLShow = 1; cFBLSelect = 2; cFBLDeselectOthers = 4; If not specified, assumes all flags on |
Method: signals
Retrieves an array of signal (DWSignal) objects for the circuit with various filtering options.
SPArray = signals
SPArray = signals(fieldName, value, ...);
SPArray = signals(fieldName, regExp, ...);
SPArray = signals(options, fieldName, value, ...);
SPArray = signals(options, fieldName, regExp, ...);
SPArray = signals(options, scope, fieldName, value, ...);
SPArray = signals(options, scope, fieldName, regExp, ...);
SPArray = signals(options);
SPArray = signals(options, scope);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| scope | int | This is used in hierarchical designs to determine how much of the hierarchy is extracted. This can be exactly one of the following values:
|
| regExp | RegExp | A regular expression that will be applied to the preceding attribute field. If the expression matches, the signal is included in the list. |
| value | String | The value of the preceding attribute field that must be matched exactly for the signal to be included in the list. |
| fieldName | String | The name of an attribute field. The following parameter can be a string value, which must be exactly equal for the signal to be included, or can be a regular expression. Any number of fieldName/value or fieldName/regExp pairs can be specified. |
| options | int | This is a set of flags that allows you to filter the list to include/exclude various categories of signals. This argument can be any OR of the following values:
|
Returns an SPArray object containing a list of all signals(DWSignal) specified by the option parameters.
Returns an array with one element for each signal requested. All signals on all pages of this circuit are included.
If no parameters are specified, you will get a list of all the signals on all pages of the given circuit.
A variety of different combinations of parameters can be passed, and the meaning of each is determined by the data type of the parameter. If the first one or two parameters are integers, then they are interpreted as the options and scope parameters, respectively. Once any non-integer (normally a string) parameter is encountered, this is assumed to be an attribute value filter, as follows
Any remaining parameters are taken as attribute field name/value or field name/regular expression pairs. Any signals matching the given values or patterns will be included in the list.
Note that this array is not updated automatically. If you perform other operations that add or delete signals, this array will be invalid and should be retrieved again. This can cause the program to bomb if misused!
cct = currentCircuit();
sigs = cct.signals(); // All the non-pseudo-signals in the circuit
sigs = cct.signals("Voltage", "120", "Name", /V1.+/); // All signals with Voltage field equal to "120" and Name matching the given expression
sigs = cct.signals(1); // All selected signals in the circuit
Method: undo
Performs an undo operation, exactly as if the Undo menu command was selected by the user.
void undo();
Method: zap
Applies a zap (selective delete) operation, exactly as if the user had clicked the Zap cursor at the given position
void zap(posX, posY);
void zap(pageNum, posX, posY);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| pageNum | int | Page number for the operation to be applied to. If not specified, the current page is assumed |
| posY | int | Y position of the zap location in circuit coordinates |
| posX | int | X position of the zap location in circuit coordinates |
The given position does not have to be exact as the same hit testing methods are used as if this was performed by the user