Method: addDevice
Adds a device to the current circuit
All arguments are identical to DWCircuit.addDevice
Method: callObject
Calls a method of a specified ActiveX object in the current circuit.
void callObject(objName, methodName, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| objName | String | The name of the object to call |
| methodName | String | The name of the object's method to call |
Returns the value returned by the method call
All following arguments are passed to the method call
Method: convertDate
Converts date and time values from the Windows integer format used internally for date stamps and file info to and from the JavaScript date format that can be used to display formatted date and time values.
int = convertDate(dateObj);
date = convertDate(intDate);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| intDate | int | An integer representing a date in Windows internal format. This can also be a string representation of an integer |
| dateObj | Date | A JavaScript Date object, created using new Date() |
The internal Windows format used for datestamps on files and devices is the number of seconds since January 1, 1970.
IMPORTANT NOTE: The date value returned is NOT a JavaScript Date object. To create a JavaScript date object that can be used to extract year/month/day fields, format output, etc. use the expression dateObj = new Date(returnedValue);
Method: currentCircuit
Returns the currently active circuit.
DWCircuit = currentCircuit
Method: currentDesign
Returns the currently active design, i.e. the design containing the currently active circuit, or returns the open design matching the given file path.
DWCircuit = currentDesign
DWCircuit = currentDesign(path);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| path | String | The file path of a currently open design, or any subset of the file path. If two designs contain the same string, this will return the first one encountered. This is case-insensitive. |
Property: currentLibrary
Returns the the library currently selected in the parts palette, or null if no library or all libraries are selected.
DWLibrary = currentLibrary
Method: currentPage
Returns a DWPage object representing the currently active page, or null if none
DWPage = currentPage
Property: defaultDocDir
Gets or sets the default document directory, i.e. the directory used by Open and Save As operations
defaultDocDir = String
String = defaultDocDir
Property: defaultObject
Returns the object on which this script was invoked, if any.
DWObject = defaultObject
defaultObject = DWObject
The type of object returned depends on the type of object selected in the circuit and could be one of DWCircuit, DWDevice, DWSignal, or DWPin
This is only set if the script was invoked as a result of a command on a single selected circuit object and will return null otherwise. This property can be set directly for the purpose of mimicking a call by the system when invoking another script.
Property: displayScalePercent
Gets the display scaling percentage specified by the user for the Windows system, expressed as an integer. This is typcically 100 or may be 125 or 150 for higher resolution screens.
int displayScalePercent();
Read only
Property: documentIsOpen
bool documentIsOpen(path);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| path | String | The full file path to the desired document file. |
No directory search is applied to this file so the full path must match the path to the open document in order to be found.
Method: doObjectPropertiesDialog
Opens a properties dialog and displays the objects properties according to its schema
bool = doObjectPropertiesDialog(object);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| object | Object | The object whose properties will be displayed |
Returns true if the call is successful, false otherwise.
Method: fontDPISetting
Returns an integer representation of the "font size" setting from the system's control panel, or possibly an override value set by the user in the application.
int fontDPISetting();
Returns 100 for normal font size, or (typically) 125, 150 or 200 for larger percentage size settings
Method: getAppVersionInt
Provides the version number of the application that is hosting the script.
Integer = getAppVersionInt
Returns an integer specifying the version number. See below for more details.
The integer format is intended for internal use within a script to determine whether data was created using an earlier or later version of the software. The integer format is:
(major version # * 16384) + (minor version # * 4096) + (increment # * 256) + (release type * 16) -- 1 = development, 2 = alpha, 3 = beta, 4 = release + step #
For example, the version 3.2b3 would give 57395. If any part of the version number is not given in the usual written form, it is assumed to be zero. This numbering scheme ensures that the integer value always increases for later versions.
Method: getAppVersionLong
Provides the version number of the application that is hosting the script.
String = getAppVersionLong
Returns a string specifying the version number. See below for more details.
This method returns a string specifying the application name and version number in a human-readable form, for example DesignWorks version 3.2.4b1
Method: getAppVersionShort
Provides the version number of the application that is hosting the script.
String = getAppVersionShort
Returns a string specifying the version number. See below for more details.
This method returns a string specifying the application name and version number in an abbreviated form, for example DW3.2.4b1
Method: getibrary
Get a referemce to a symbol library given its libID
DWLibrary = getibrary(libID);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| libID | int | Integer handle to the library |
Returns a library object, or null if the libID does not refer to a library
Method: getOpenDesigns
Returns a list of all currently open designs SPArray getOpenDesigns(); SPArray getOpenDesigns(filter); #param filter, String, A filter string that is applies when adding items to the list. If the entire file path of a design contains this string (not case sensitive), it is added. If this is not supplied, all designs are included
Returns an SPArray containing a DWCircuit object for each open (user-visible) design
Method: getPrivateCLSID
Returns a string form of the private CLSID associated with the given progID. This allows the caller to connect multiple times to an object in the current instance of the application
String getPrivateCLSID(progID);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| progID | string | The human-readable program ID associated with the object |
Returns a string form of the CLSID in the format {00000000-0000-0000-0000-000000000000} or null if the progID was not found
Method: getScaleFromUnit
Returns a floating-point scale value representing the given unit, e.g. kV return 1000, uF returns 0.000001, etc.
double = getScaleFromUnit(unit);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| unit | String | A string representing the units |
Method: libraryList
Returns an SPArray object containing a DWLibrary object for each of the currently open libraries.
SPArray = libraryList
SPArray = libraryList(excludeReadOnly);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| excludeReadOnly | bool | TRUE to list only libraries that are writeable, defaults to false. |
Method: loadExternalObject
object loadExternalObject(id);
object loadExternalObject(id, want64Bit);
object loadExternalObject(id, want64Bit, quiet);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| quiet | bool | True to disable all errors boxes, true to display an error box for any errors that occur, defaults to true |
| want64Bit | bool | True to attempt to load a 64-bit server, false for 32-bit, defaults to false |
| id | String | The Program ID (progID) or Class ID (CLSID) of the server |
Returns a reference to the loaded object or null if any error
Method: loadType
Loads a device type definition from its library given a library ID
DWType loadType(libID);
DWType loadType(libID, displayOnly);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| libID | int | An integer handle to the type, which specifies the library and the type within the library |
| displayOnly | bool | If true, the caller is going to use this object only to display information about the type and will not give the user access to use it in a design, i.e. it can bypass protection |
A DWType object if successful, or null if unsuccessful.
Method: newDesign
Creates a new, empty design with or without opening it in a visible window.
DWCircuit = newDesign
DWCircuit = newDesign(visible);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| visible | bool | true to open the design in a visible window, false to open it as and internal structure only, invisible to the user. Defaults to true. |
Returns a DWCircuit object for the design or null if the operation failed.
This creates a new, empty design with default settings, without referring to any template.
Method: newDocument
Create a new document window within the application given the document type string. Optionally provide data to fill the document with.
bool = newDocument(docType);
bool = newDocument(docType, data);
bool = newDocument(docType, data, path);
bool = newDocument(docType, data, path, object);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| docType | String | A string that uniquely identifies a document type. This is the name that is used in the system registry to register the type, or any unique subset of the name. Not case sensitive. |
| object | object | The object (normally a DWDevice) that will be the parent object for this new document. Default is null. |
| path | String | Location to save the new document file. If not specified, the document is opened but not saved. |
| data | String | Data used to fill the new document. The format and meaning of the data depend on the document type. |
Returns true if the document opened successfully, false otherwise
Method: newSymbol
Creates a new, empty symbol with or without opening it in a visible editor window.
void newSymbol();
void newSymbol(visible);
void newSymbol(typeName);
void newSymbol(typeName, visible);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| typeName | String | the initial name of the symbol, can be changed by the user if the editor is opened in a visible window |
| visible | bool | true to open the symbol in a visible editor window, false to open it as and internal editor only, invisible to the user. Defaults to true. |
Method: newTextDocument
Create a new text document window within the application. Optionally provide data to fill the document with.
bool = newTextDocument
bool = newTextDocument(data);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| data | String | Text data used to fill the new document |
Returns true if the document opened successfully, false otherwise
Method: openDesign
Opens a design file, with or without prompting the user and with or without opening it in a visible window.
DWCircuit = openDesign
DWCircuit = openDesign(visible);
DWCircuit = openDesign(filePath);
DWCircuit = openDesign(filePath, visible);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | The complete file path of the design file to open |
| visible | bool | true to open the design in a visible window, false to open it as and internal structure only, invisible to the user. Defaults to true. |
Returns a DWCircuit object for the design or null if the open failed.
If no argument is provided, this is equivalent to selecting the Open Design command.
Method: openDesignDeferred
Opens a design file after the processing of the current script or program operaton has completed.
void openDesignDeferred();
void openDesignDeferred(filePath);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | The complete file path of the design file to open |
None
This method is similar to openDesign except that the open operation is deferred until the program is idle, i.e. this script has completed execution and the user operation that invoked it has completed. This is intended specifically for use in scripts that may be invoked by a user menu command like "Open Design" where opening another design during the process may cause recursion or other confusing results.
There is no return value because the operation has not been completed yet when this method returns
Property: openDocument
bool openDocument(path);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| path | String | The full file path to the desired document file. |
No directory search is applied to this file so the full path must match the path to the open document in order to be found.
Method: openLibrary
Opens a symbol library file, or returns a reference to it if the specified file is already open.
DWLibrary = openLibrary(file);
DWLibrary = openLibrary(file, visible);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| file | String | The file name of the symbol library. This can be a full path or a partial path relative to the program location. |
| visible | bool | TRUE to make the library visible to the user (i.e. it appears in the parts palette), false to keep it hidden, defaults to TRUE. |
Method: readIniString
Reads a string value from the application's INI file or state file.
String = readIniString(section, name);
String = readIniString(section, name, readState);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| section | String | The INI section name |
| name | String | The INI keyword |
| readState | bool | Pass true to read the state file instead of the INI file. Defaults to false if not specified. |
Returns the value of the string, or NULL if no such entry is found.
Two INI files are stored in the application's program folder. The file appName.INI is the initialization file that contains fixed settings and can be modified by the user. The "state" file appNameState.INI uses the same general format, but is written and read by the application to save program settings between sessions.
Method: requestDesignNotification
Requests that a method in the current script be called when a specified event occurs on this design
void requestDesignNotification(scriptObject, name1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| name1 | String | The name of the notification desired. The script must contain a method with exactly this name. This method will be called with a single argument, the DWCircuit object for this design. See below for possible notification names. |
| scriptObject | String | An object containing the script methods to call. In practice, this is usually the top level "document" object in an HTML page |
| onDesignOpen | Invoked if any design is opened |
| onDesignClose | Invoked if any design is closed |
| onDesignSelect | Invoked when any change in page activation for any design occurs |
| onDesignNameChange | Invoked when any design's name is changed |
| onDesignStructChange | Invoked when any structural circuit change occurs in any design |
| onObjectSelectChange | Invoked when the selected status of any object in the circuit occurs in any design |
Method: runExport
Runs an Export script, as if the user had selected the Export command.
bool = runExport(filePath);
bool = runExport(filePath, open);
bool = runExport(filePath, open, arg1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | A relative or absolute path to the script file. If a relative path is given, the usual rules are applied to locate it. |
| open | bool | true to open the resulting text output file in the built-in text editor after the operation completes. Defaults to false. |
| arg1 | String | an optional argument string passed to the export script. You can pass any number of these optional arguments and they are available within the export script using the notation &ARG1, &ARG2, etc. |
Returns false if the script file cannot be located, true otherwise.
Method: runExportScriptToString
Accepts the given string as an export script and returns the output it generates as a string value. This is the same as runExportToString except that in this case the actual text of the script is provided instead of the script file name. This version also accepts optional string arguments and a default object to be used in generating the report
String = runExportScriptToString(scriptText);
String = runExportScriptToString(scriptText, object);
String = runExportScriptToString(scriptText, object, arg1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| arg1 | String | An optional argument to pass to the report script. Any number of these can be passed. They are accessible in the script at &ARG1, &ARG2, etc. |
| object | DWObject | A circuit object or null. This can be a circuit, signal, device or pin object and will be the "default object" for the report, i.e. the object referred to in the top-level context of the script commands. Defaults to null. |
| scriptText | String | Contains the text of the script to run. |
Returns null if the script file cannot be located, otherwise it returns the text output generated by the report.
NOTES:
The result generated is very is the default output from the script, assuming no output file is opened. The script can still elect to explicitly open an output file and write data to the file. That data will not be included in this result.
The return value is limited in length to 10MB as the report generator must guess in advance how big a buffer to allocate for output.
Method: runExportToString
Runs an Export script and returns the output it generates as a string value. This version also accepts optional string arguments and a default object to be used in generating the report
String = runExportToString(filePath);
String = runExportToString(filePath, object);
String = runExportToString(filePath, object, arg1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | A relative or absolute path to the script file. If a relative path is given, the usual rules are applied to locate it. |
| arg1 | String | An optional argument to pass to the report script. Any number of these can be passed. They are accessible in the script at &ARG1, &ARG2, etc. |
| object | DWObject | A circuit object or null. This can be a circuit, signal, device or pin object and will be the "default object" for the report, i.e. the object referred to in the top-level context of the script commands. Defaults to null. |
Returns null if the script file cannot be located, otherwise it returns the text output generated by the report.
NOTES:
The result generated is very is the default output from the script, assuming no output file is opened. The script can still elect to explicitly open an output file and write data to the file. That data will not be included in this result.
The return value is limited in length to 10MB as the report generator must guess in advance how big a buffer to allocate for output.
Method: selectLibrary
Displays a box allowing the user to select one of the currently open libraries.
DWLibrary = selectLibrary
DWLibrary = selectLibrary(excludeReadOnly);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| excludeReadOnly | bool | TRUE to list only libraries that are writeable, defaults to false. |
Returns a DWLibrary object for the selected library, or null if the user cancels
Method: setSystemWarning
Add a system warning message that will be displayed in the system warning area on the GUI. The message is available to the user but no immediate dialog box is displayed. This is intennded for situations where it is valuable to provide information for the user to use at their convenience but that do not require interrupting the work flow
void setSystemWarning(title);
void setSystemWarning(level, title);
void setSystemWarning(source, title);
void setSystemWarning(level, source, title);
void setSystemWarning(source, title, description);
void setSystemWarning(level, source, title, description);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| description | String | An optional, longer description of the warning. This may contain additional details about the issue and is displayed only if the user asks for more information |
| title | String | The warning title. This should be a short string summarizing the warning and is displayed in the warning list |
| source | String | The source module. This should be a single word or very short title for the subsystem creating the error. This is intended to allow the user to locate the source of the problem |
| level | int | The severity level of the error, 0 = information only, 1 = low, 2 = medium, 3 = high. This is used to display a warning icon to the user and should suggest the urgency of any required action. Default is 0 |
Method: showControlPanel
Opens a new tab in the dockable status panel and creates an Internet Explorer browser instance in the panel.
bool = showControlPanel(clsid, title);
bool = showControlPanel(clsid, title, alias);
bool = showControlPanel(clsid, title, alias, filePath);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| filePath | String | A file path specifying the location of the ActiveX control (.ocx) file. If this is specified, then the control file is loaded directly from this location and the location is not determined from the system registry. In this case, it is not required for the control to be listed in the registr. Note: In order for the control to be initialized correctly, it must register itself in memory using the system call CoRegisterClassObject upon loading. Note also that the CLSID is still required in order to initialize the control. |
| title | String | The title to display in the window tab. This should be short! |
| clsid | String | The class id of the control, can be either a program ID of the form program.object (if this is registered in the system registry) or a raw GUID of the form {xxx-xxx-xxx} |
| alias | String | An internal name for the window. If this is specified, subsequent opens using the same alias will use the same window instead of opening a new one. This name is not visible to the user |
Returns true if the call is successful, false otherwise.
NOTE: Due to the way window and control creation is queued by the system, the control will not be created until some time after the call is completed. This method returning true indicates only that the request was queued successfully.
Method: showCustomPanel
Opens a new tab in the dockable status panel and creates an Internet Explorer browser instance in the panel.
bool = showCustomPanel(url, title);
bool = showCustomPanel(url, title, alias);
bool = showCustomPanel(url, title, alias, object);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| title | String | The title to display in the window tab. This should be short! |
| url | String | The URL (web address or full file path) of the resource to display in the browser |
| object | Object | An object that will be passed as the second argument to the onopen method in the document page. NOTE: If the page keeps a global reference to this object (i.e. outside the scope of the onopen method) then it should set this reference to null when the page exits or it is no longer needed. |
| alias | String | An internal name for the window. If this is specified, subsequent opens using the same alias will use the same window instead of opening a new one. |
Returns true if the call is successful, false otherwise.
NOTE: Due to the way window and browser creation is queued by the system, the browser will not be created and navigated to the given URL until some time after the call is completed. This method returning true indicates only that the request was queued successfully.
Method: uiAddAction
Specify an action to take place in response to application user interface event
void uiAddAction(event, action);
void uiAddAction(event, action, args, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| event | String | Specifies the script to run, file to open or event to fire. See system documentation on custom menus for more information. |
| action | String | Specifies the script to run, file to open or event to fire. See system documentation on custom menus for more information. |
| args | Object | A value or array of values to be passed to whoever handles the user action. Any number of additional arguments can be passed. |
int, command ID of the event or -1 if any error
Method: uiAddControl
Add a control (menu item or toolbar control) to the application user interface
void uiAddControl(action, ctrlName);
void uiAddControl(action, site, ctrlName, eventName, statusMsg, iconPath, formatFlags, args, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| formatFlags | int | An optional integer specifying the type and format of the control. If not specified, a simple button is assumed |
| eventName | String | An optional name to be used to refer to this event, e.g. for enabling/disabling controls, etc. |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| statusMsg | String | An optional string specifying the message that is displayed in the app status bar when the user hovers over this item |
| ctrlName | String | The hierarchical name of the control to set, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
| action | String | Specifies the script to run, file to open or event to fire. See system documentation on custom menus for more information. |
| iconPath | String | An optional string specifying the location of the tool icon |
| args | Object | A value or array of values to be passed to whoever handles the user action. Any number of additional arguments can be passed. |
int, ID of the control or -1 if any error
Method: uiControlBlink
Starts an automatic timed switching between any number of predefined background states for the given custom control.
void uiControlBlink(ctrlName, stateLo, stateHi, intervalMillis, numReps);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| stateHi | int | The state number of the last background to set. If the given state number is not found, the background is set to its default value |
| numReps | int | The number of times that the entire state sequence will be repeated. If this is <= 0 then the sequence is repeated indefinitely until cancelled. Once the specified number of repetitions has been displayed, the control reverts to its default background |
| intervalMillis | int | The interval between state changes in milliseconds |
| stateLo | int | The state number of the first background to set. If the given state number is not found, the background is set to its default value |
| ctrlName | String | The name of the control to set, usually as defined in the INI file |
This is used to start automatic timed sequencing through a number of background states for a custom control, allowing animated graphical display of progress or different states to the user. The states are predefined for the control, usually in the INI file.
The sequence starts with the state number given by stateLo and steps sequentially through integer-numbered states to and including stateHi. If any state number is undefined, the default background is used for that state.
uiSetControlState can be used to cancel blinking.
Method: uiFireDelayedEvent
Fires a user-interface event, that is, causes any actions linked to the event to be executed
void uiFireDelayedEvent(id, delaySecs);
void uiFireDelayedEvent(eventName, delaySecs);
void uiFireDelayedEvent(id, delaySecs, arg1, ...);
void uiFireDelayedEvent(eventName, delaySecs, arg1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| eventName | String | An event name used to create a control or event |
| delaySecs | int | The delay in seconds until the actions associated with this event are invoked. If this is zero, the actions will be invoked immediately after the application enters the idle state. |
| arg1 | String | An argument to be passed to the event handler. Any number of arguments can be passed. The usage of these arguments depends on the event handler |
| id | int | The event id that was returned when a control or event was created, or can be obtained using uiGetControlID |
Returns any value generated by actions linked to the event
Method: uiFireEvent
Fires a user-interface event, that is, causes any actions linked to the event to be executed
void uiFireEvent(id);
void uiFireEvent(eventName);
void uiFireEvent(id, arg1, ...);
void uiFireEvent(eventName, arg1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| eventName | String | An event name used to create a control or event |
| arg1 | String | An argument to be passed to the event handler. Any number of arguments can be passed. The usage of these arguments depends on the event handler |
| id | int | The event id that was returned when a control or event was created, or can be obtained using uiGetControlID |
Returns any value generated by actions linked to the event
Method: uiGetControlChecked
Gets the checked property of a control in the application user interface
void uiGetControlChecked(id);
void uiGetControlChecked(site, ctrlName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| ctrlName | String | The hierarchical name of the control to set, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
| id | int | The control id that was returned when the control was created |
bool, The current value of the checked property for this control
Method: uiGetControlEnabled
Gets the enabled property of a control in the application user interface
void uiGetControlEnabled(id);
void uiGetControlEnabled(site, ctrlName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| ctrlName | String | The hierarchical name of the control to set, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
| id | int | The control id that was returned when the control was created |
bool, The current value of the enabled property for this control
Method: uiGetControlID
Get the integer ID of a control in the application user interface
void uiGetControlID(ctrlName);
void uiGetControlID(site, ctrlName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| ctrlName | String | The hierarchical name of the control to set, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
int, ID of the control or -1 if not found
Method: uiGetControlText
Get the text value of a control in the application user interface
String uiGetControlText(ctrlName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| ctrlName | String | The name of the control to set |
Method: uiGetControlTitle
Get the text value of a control in the application user interface
String uiGetControlTitle(ctrlName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| ctrlName | String | The name of the control to set |
Method: uiProgressOpenPercent
Opens a percentage progress bar control in the application's status area, with an option text title.
void uiProgressOpenPercent();
void uiProgressOpenPercent(title);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| title | String | optional title to be displayed to the left of the moving bar |
No return value
It is not necessary to call this method before calling uiProgressPercent unless you want to specify a title. The bar closes automatically when the application is idle, usually after script execution has terminated
Method: uiProgressPercent
Update percentage progress value in progress bar
void uiProgressPercent(value);
void uiProgressPercent(value, outOf);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| value | int | The current progress value. If outOf is not specified, this will range from 0 for no progress to 100 for complete. If outOf is specified, the value can range from 0 to the value of outOf |
| outOf | int | The maximum progress value. The minimum is always 0. Defaults to 100 |
No return value
If you want to display a text title to the left of the progress bar, call uiProgressOpenPercent before starting the percent progress. If no title is needed, it is not necessary to call uiProgressOpenPercent. The bar closes automatically when the application is idle, usually after script execution has terminated
Method: uiProgressText
Displays a status message in the applications progress bar
void uiProgressText(msg);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| msg | String | The text message to be displayed |
No return value
The status message is cleared automatically when the program is idle, normally when script execution terminates.
Method: uiRemoveControl
Remove a control (menu item or toolbar control) from the application user interface
void uiRemoveControl(eventID);
void uiRemoveControl(eventName);
void uiRemoveControl(site, ctrlName);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| eventID | int | Integer event identifier, returned by other ui methods |
| eventName | String | An optional name to be used to refer to this event, e.g. for enabling/disabling controls, etc. |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| ctrlName | String | The hierarchical name of the control to remove, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
int, ID of the control or -1 if any error
Method: uiSetApplicationTitle
Sets the text displayed in the application main window title bar
void uiSetApplicationTitle();
void uiSetApplicationTitle(text);
void uiSetApplicationTitle(text, position);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| position | int | 0 => replace the entire title with the given text, 1 => the given text replaces the document path part of the title, 2 => the text replaces the application name part of the title, 3 => the text is appended to the existing title, defaults to 3 |
| text | String | The title text to be displayed |
If you use option 0 to set the full title, this will override all other settings until it is cleared. Calling this method with no argument or with an empty text argument resets the title to its default value
Method: uiSetBlocked
Sets the enabled status of all document editing and user interface controls
void uiSetBlocked(block, timeoutMillis);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| block | Bool | true to disable all user interface controls and document editing actions, false to re-enable |
| timeoutMillis | int | A timeout until the user interface is unblocked automatically, in milliseconds. If < 0 or not specified, no automatic unblocking action is taken. Ignored if block is false. |
No return value
Method: uiSetControlChecked
Sets the checked property of a control in the application user interface
void uiSetControlChecked(id, checked);
void uiSetControlChecked(site, ctrlName, checked);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| checked | bool | The new value for the checked state |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| ctrlName | String | The hierarchical name of the control to set, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
| id | int | The control id that was returned when the control was created |
None
Method: uiSetControlEnabled
Sets the enabled property of a control in the application user interface
void uiSetControlEnabled(id, enabled);
void uiSetControlEnabled(site, ctrlName, enabled);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| enabled | bool | The new value for the enabled state |
| site | String | An optional string specifying the location of the item. If not specified or empty, the main toolbar is assumed |
| ctrlName | String | The hierarchical name of the control to set, i.e. tab\ngroup\nitem or tab\ngroup\nitem\nsubItem |
| id | int | The control id that was returned when the control was created |
None
Method: uiSetControlState
Sets the background of the given control to be one of a number of previously defined states
void uiSetControlState(ctrlName, stateNum);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| ctrlName | String | The name of the control to set, usually as defined in the INI file |
| stateNum | int | The state number of the background to set. If the given state number is not found, the background is set to its original default value |
This is used to select one of a number of background states for a custom control, allowing graphical display of different states to the user. The states are predefined for the control, usually in the INI file.
NOTE: If uiControlBlink has been used to start a blinking sequence, calling this method will cancel the blinking and revert to the given state background.
Method: uiSetControlText
Set the text of a control in the application user interface
void uiSetControlText(ctrlName, text);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| ctrlName | String | The name of the control to set |
| text | String | The text to apply to the control. If this is omitted, the control text is set to empty |
Method: uiSetControlTitle
Set the title (label) of a control in the application user interface
void uiSetControlTitle(ctrlName, title);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| title | String | The text to apply to the control. If this is omitted, the control title is set to empty |
| ctrlName | String | The name of the control to set |
Method: unrequestDesignNotification
Requests that a previously-requested notification be removed
void unrequestDesignNotification(scriptObject, name1, ...);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| name1 | String | The name of the notification desired. The script must contain a method with exactly this name. This method will be called with a single argument, the CRCircuit object for this design. See below for possible notification names. |
| scriptObject | String | An object containing the script methods to call. In practice, this is usually the top level "document" object in an HTML page |
The arguments must be exactly the same as for requestDesignNotification
Method: writeStateString
Reads a string value from the application's INI file or state file.
void writeStateString(section, name, value);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| value | String | The new value |
| section | String | The INI section name |
| name | String | The INI keyword |
nothing
The "state" file appNameState.INI uses the same general format as the INI file, but is written and read by the application to save program settings between sessions. The file format is very simple and will only accept one-line text values without any control characters in them.