Keyword Index

Object: DWCircuit

  • addDevice - Adds a device to the circuit (i.e. places it on the diagram)
  • addGraphic - Adds a graphic item to the circuit (i.e. places it on the diagram)
  • addPage - Adds one more page to the circuit
  • 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.
  • addSignal - Adds a signal to the circuit.
  • allInstances - Gets a string array containing the instance locators for all possible physical instances of this object
  • attributeList - Gets or sets the attribute list (i.e. the collection of all attribute values) associated with this object.
  • 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

  • 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.
  • clear - Deletes the selected objects in the circuit. This is equivalent to the Clear menu command.
  • close - Closes the design associated with this circuit with or without prompting the user.
  • copy - Copies the selected objects in the circuit to the system clipboard or to a given circuit.
  • 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.
  • defineAttribute - Defines or modifies the definition of an attribute field in the design associated with this circuit
  • 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.
  • design - Gets the design containing this circuit, may be itself if this is a top-level circuit. Read-only
  • devices - Retrieves an array of device objects for the circuit with various filtering options.
  • fileAppVersion - An integer indicating the program version that created the associated design file. Read only.
  • fileDir - The directory path of the file associated with this circuit, i.e. the name of the directory containing the file. Read only.
  • fileFormatVersion - An integer indicating the format version of the associated design file. Read only.
  • fileName - The name of the file associated with this circuit, i.e. the file name without any directory path. Read only.
  • filePath - The full directory path and file name of the file associated with this circuit. Read only.
  • findByLocator - Searches the design containing this circuit for an object (circuit, device, signal or pin) that matches the given locator string.
  • findObjectByName - Searches given circuit for an ActiveX object with the given name. This gives direct access to the objects properties and methods.
  • frame - Gets the bouding frame for the given page of this circuit
  • getAttribute - Gets an attribute value from this object
  • getAttributeDefinition - Returns the internal field number, option flags and maximum value length for the field
  • getAttributeFieldNames - Returns an array of field names matching the given option flags
  • getAttributeVis - Gets the visibility of an attribute on this object
  • getCircuitLocatorByName - Returns the locator of a circuit given a hierarchical name.
  • 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
  • getDefaultSignalName - Returns the next unused name having the given prefix. The prefix can be either given explicitlyor obtained from the design's default settings
  • getDeviceLocatorByName - Returns the locator of a device given a hierarchical name.
  • getLineStyle - Creates a new line style or gets an existing line style associated with this design
  • getNameByLocator - Returns the hierarchical name of the object that matches the given locator string.
  • getProperties - Gets a properties object associated with this object.
  • getProperty - Gets a named property associated with this object.
  • getSignalLocatorByName - Returns the locator of a signal given a hierarchical name.
  • instanceHierName - Gets or sets the selected physical instance of the circuit using its hierarchical name to identify it
  • instanceLocator - Gets or sets the selected physical instance of the circuit using its locator to identify it
  • isLocked - Gets the "locked" status of the circuit, i.e. whether it can be opened by the user.
  • 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
  • isPhysical - Gets or sets the "physical" hierarchy mode of the design
  • isReadOnly - Gets or sets the "read-only" status of the circuit
  • locateDevices - Retrieves an array of device objects for the circuit with various filtering options.
  • locator - Gets the locator string of the circuit
  • name - Gets the name of the circuit, i.e. the name of the file it is saved in.
  • objType - Returns a string with the name of this object class "DWCircuit".
  • open - Opens a window on the circuit, or just brings an existing window to the front if it is already open.
  • pages - Retrieves an array of page objects for the circuit
  • parentDevice - Gets the parent device of this circuit, if it is a subcircuit, or null if this is a top-level circuit. Read-only.
  • 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.
  • paste - Copies the contents of the system clipboard or a given source circuit to this circuit.
  • pins - Retrieves an array of pin objects for the circuit with various filtering options.
  • 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.
  • redo - Performs a redo operation, exactly as if the Redo menu command was selected by the user.
  • redraw - Force a redraw of the circuit window
  • save - Saves the design associated with this circuit, as if the user had selected the Save command.
  • saveAs - Saves the design associated with this circuit to a file. The file can be specified directly or by prompting the user.
  • 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.
  • 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.
  • select - Makes this circuit current by bringing one of its windows to the front
  • 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.
  • selectedObjectsProperties - Gets or sets the merged values of all selected objects in this circuit.
  • setAttribute - Sets an attribute value in this object
  • setAttributeDefaultVis - Sets the default visibility for the named attribute field for objects created in this design.
  • setProperty - Sets a named property associated with this object.
  • showByLocator - Searches the design containing this circuit for an object (circuit, device, signal or pin) that matches the given locator string.
  • signals - Retrieves an array of signal (DWSignal) objects for the circuit with various filtering options.
  • undo - Performs an undo operation, exactly as if the Undo menu command was selected by the user.
  • zap - Applies a zap (selective delete) operation, exactly as if the user had clicked the Zap cursor at the given position
  • 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:

    Returns a DWDevice object representing the new device

    Remarks:

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

    Returns:

    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

    Returns:

    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:

    Returns a DWDevice object representing the new device

    Remarks:

    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:

    Returns a DWSignal object representing the new signal

    Remarks:

    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:

    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.

    Remarks:

    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:

    Returns the internal field number (1..N) for the defined or modified field, or 0 if any error

    Remarks:

    This table defines the available options.
    LetterDescription
    AAllow carriage return
    CDefined for design
    DDefined for devices
    FFixed field (cannot be removed once defined, usually only used for fields required for internal operation)
    GGroup with Name field
    LLocation fixed, cannot be repositioned by the user
    MTemporary field, value is not saved to file
    NOnly valid name characters allowed in value (this is not enforced in this version)
    PDefined for pins
    RRotate with the device
    SDefined for signals
    UOnly valid numeric characters allowed in value (this is not enforced in this version)
    VMake value visible by default (other settings in the program affect visibility and may override this setting)
    WShow field name with value by default
    XValue fixed, cannot be edited by the user
    YPrimary 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:
    • 3 HIER_SCOPE_DESIGN
    • 4 HIER_SCOPE_CIRCUIT
    • 5 HIER_SCOPE_HEREDOWN
    • 6 HIER_SCOPE_TOPCIRCUIT
    • 7 HIER_SCOPE_OPEN.
    If this parameter is not specified, the specified circuit level is scanned.
    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:
    • 1 OPTION_SELECTED_ONLY
    • 2 OPTION_INCL_PSEUDO_DEVS
    • 4 OPTION_INCL_DEFS
    • 8 OPTION_EXCL_INSTANCES
    • 128 OPTION_INCL_PARENT_DEV
    • 512 OPTION_IGNORE_MODE
    If this parameter is not given, you will get all non-pseudo-devices in the given circuit.
    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:
    • -1 RESTRICT_NONE
    • 0 RESTRICT_REPORT
    • 1 RESTRICT_PACKAGE
    • 2 RESTRICT_OPEN.
    If this parameter is not included, the Restrict attribute is ignored.

    Returns:

    Returns an SPArray object containing a list of all devices(DWDevice) specified by the option parameters.

    Remarks:

    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!

    Example:

    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();

    Remarks:

    NOTE: The returned value is a 20-bit binary integer which can be interpreted as 5 hex digits.

    For example, version 4.2.1 will be 0x42100. Version 4.5b1 will be 0x450b1, etc. The various parts can be extracted using standard bit operations, e.g. the major version number can be extracted using major = (v & 0xf0000) >> 16

    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();

    Remarks:

    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:

    Returns a DWDevice, DWSignal, DWCircuit or DWPin object representing the object found or null if no match.

    Remarks:

    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:

    Returns a direct interface to the object or null if no match.

    Remarks:

    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:

    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:

    Returns the option string, described below. Returns an empty string if there is no definition for the given name

    Remarks:

    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:

    Returns an array of names

    Remarks:

    This table defines the available options.
    FlagDescription
    CDefined for circuit (design)
    DDefined for devices
    PDefined for pins
    SDefined for signals
    YPrimary 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:

    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:

    Returns a string containing the locator name of the circuit, or null if not found.

    Remarks:

    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

    Remarks:

    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

    Remarks:

    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:

    Returns a string containing the locator of the device, or null if not found.

    Remarks:

    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:

    Returns a string containing the hierarchical name of the object, or null if not found.

    Remarks:

    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:

    Returns a string containing the locator of the signal, or null if not found.

    Remarks:

    NOTES:

    Property: instanceHierName

    Gets or sets the selected physical instance of the circuit using its hierarchical name to identify it

    String instanceHierName();

    instanceHierName = String

    Remarks:

    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

    Remarks:

    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();

    Remarks:

    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:
    • 1 OPTION_SELECTED_ONLY
    • 2 OPTION_INCL_PSEUDO_DEVS
    • 4 OPTION_INCL_DEFS
    • 8 OPTION_EXCL_INSTANCES
    • 128 OPTION_INCL_PARENT_DEV
    • 512 OPTION_IGNORE_MODE
    If this parameter is not given, you will get all non-pseudo-devices in the given circuit.

    Returns:

    Returns an SPArray object containing the locators of all devices matching the option parameters.

    Remarks:

    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.

    Example:

    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();

    Remarks:

    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();

    Remarks:

    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:

    Returns an SPArray object containing a list of all pages in this circuit

    Remarks:

    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();

    Returns:

    DWDevice object representing the parent device of this subcircuit

    Remarks:

    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();

    Returns:

    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:
    • 3 HIER_SCOPE_DESIGN
    • 4 HIER_SCOPE_CIRCUIT
    • 5 HIER_SCOPE_HEREDOWN
    • 6 HIER_SCOPE_TOPCIRCUIT
    • 7 HIER_SCOPE_OPEN.
    If this parameter is not specified, the specified circuit level is scanned.
    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:
    • 1 OPTION_SELECTED_ONLY
    • 2 OPTION_INCL_PSEUDO_DEVS
    • 4 OPTION_INCL_DEFS
    • 8 OPTION_EXCL_INSTANCES
    • 128 OPTION_INCL_PARENT_DEV
    • 512 OPTION_IGNORE_MODE
    If this parameter is not given, you will get all non-pseudo-devices in the given circuit.
    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:
    • -1 RESTRICT_NONE
    • 0 RESTRICT_REPORT
    • 1 RESTRICT_PACKAGE
    • 2 RESTRICT_OPEN.
    If this parameter is not included, the Restrict attribute is ignored.

    Returns:

    Returns an SPArray object containing a list of all pins (DWPin) specified by the option parameters.

    Remarks:

    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!

    Example:

    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:

    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:

    Returns a boolean value true if the save succeeded, false if it failed or was cancelled by the user in response to a prompt.

    Remarks:

    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:

    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();

    Remarks:

    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.

    Returns:

    Null.

    Remarks:

    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:
    • 3 HIER_SCOPE_DESIGN
    • 4 HIER_SCOPE_CIRCUIT
    • 5 HIER_SCOPE_HEREDOWN
    • 6 HIER_SCOPE_TOPCIRCUIT
    • 7 HIER_SCOPE_OPEN.
    If this parameter is not specified, the specified circuit level is scanned.
    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:
    • 1 OPTION_SELECTED_ONLY
    • 512 OPTION_IGNORE_MODE
    • 2048 OPTION_INCLUDE_BUSSES
    If this parameter is not given, you will get all non-pseudo-signals in the given circuit.

    Returns:

    Returns an SPArray object containing a list of all signals(DWSignal) specified by the option parameters.

    Remarks:

    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!

    Example:

    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

    Remarks:

    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