Keyword Index

Object: SPScript

  • addScriptSearchPath - Adds a new directory to the list of the directories that will be searched for scripts whenever a script file name is specified.
  • alert - This displays a simple box with an OK button and the given string.
  • appendFile - Works identically to writeFile except that data is appended to an existing file, instead of replacing it.
  • assert - This displays a simple box with an OK button and the given string.
  • command - Runs the given DOS-style command.
  • compareBinary - Compares two data items for an exact binary equivalence. This can be used to verify an exact copy after file or network operations.
  • confirm - This displays a simple box with OK and Cancel buttons and the given string.
  • convertCRLF - Converts the given string from internal LF-only to Windows-style CR/LF line termination.
  • ConvertSlashes - Gets or sets the status of the global "convert slashes in filenames" flag.
  • createDirectory - Creates the specified directory.
  • decrypt - Decrypts the given data and returns a new array containing the decrypted block.
  • deleteDirectory - Deletes the given directory, including all its contents.
  • deleteFile - Deletes the specified file.
  • deleteFiles - Deletes all files and directories matching the given pattern.
  • encrypt - Encrypts the given data and returns a new array containing the encrypted block.
  • getAppDataDir - Gets the directory path of the user's application data directory, i.e. the default location where temporary and writeable program data files are stored.
  • getAppDir - Gets the directory path of the application, i.e. the location where the main application is stored.
  • getDocRootDir - Gets the directory path of the document root directory, i.e. the default location where user files are stored.
  • getEnv - Gets the value of a system environment variable.
  • getFileList - Generates a list of files in the given directory.
  • getGlobalNames - Returns an array list of the names of all currently set global values
  • getGlobalValue - Gets a value stored in a global object
  • getIniDirs - Gets a list of the directories specified as a keyword in the INI file(s)
  • getIniItem - Gets the value of an item in the application ini (initialization) file
  • getPublicDataDir - Gets the directory path of the public program data directory, i.e. the default location where temporary and writeable program data files are stored that is accessible to all users. Under Windows XP, this usually the "All Users" user folder, under Vista, this will be the hidden "ProgramData" folder.
  • getRandomInt - Returns a random integer in the given range
  • getScriptArg - Gets the value of a positional argument passed when the script was invoked.
  • getScriptSearchPaths - Gets a list of the directories that will be searched for scripts whenever a script file name is specified.
  • getStateItem - Gets the value of an item in the application state file
  • getTextFromClipboard - Returns a string containing any text on the clipboard.
  • getTickCount - Gets the system tick count, i.e. the time in milliseconds since the system was last restarted. The value is returned as a double.
  • getWordsFromText - Creates an array of the "words" in a text string.
  • halt - Immediately stops execution of the script.
  • htmlProperties - This displays a property page with individual sheets defined using HTML.
  • isUserAdmin - Returns true if the current computer user has system administrator privileges.
  • loadVar - Loads a variable value that was saved using saveVar.
  • locateScriptFile - Find a file using the default script search paths
  • makeSafeXMLString - Converts the given string to a string that is safe to include as a string constant in an XML (or HTML) file
  • navigate - Start the default Web browser and pass it the given URL
  • NetPadFile - Creates a new NetPadFile object.
  • parseScriptFile - This is the same as parseScriptText but the source is a file instead of a literal string.
  • parseScriptText - Parses the given string as if it was part of the current script. Any global objects and methods in the current script are accessible to the new script and any top level items defined in the new script will be accessible to the calling script. Any top level statements in the added script are executed immediately. If any one of these statements is an expression that generates a value, that value is returned.
  • printf - Generates formatted text output to the console window.
  • progress - Writes text to the application's status bar progress box
  • prompt - This displays a simple box with OK and Cancel buttons and one or more text entry boxes.
  • putTextOnClipboard - Places the given text on the clipboard.
  • run - Runs an application or opens a file. This is equivalent to double-clicking on the specified file in the Explorer. If the file is an application, it is started. If the file is a document, the system attempts to find the associated application and open it.
  • saveVar - Saves a variable value to the system registry.
  • setGlobalValue - Saves an arbitrary value to a global object
  • setScriptResult - Set the script result value that will be returned to the process that invoked the script
  • setScriptSearchPaths - Sets the list of the directories that will be searched for scripts whenever a script file name is specified.
  • setStateItem - Sets the value of an item in the application state file
  • sleep - Pauses execution of the script for the given number of milliseconds.
  • SPArray - Creates a new SPArray object, optionally containing some initial data.
  • SPColour - Creates an SPColour object, which represents a colour for display graphics operations
  • SPDatabase - Creates a new SPDatabase object.
  • SPDatastash - Creates a new SPDatastash object.
  • SPFile - Creates a new SPFile object.
  • SPHTMLDialog - Creates a new, empty SPHTMLDialog object which is used to display an HTML dialog or property sheet.
  • SPPoint - Creates a new SPPoint object, used to represent a graphical point with coordinates X and Y
  • SPPropsObject - Creates a new, empty SPPropsObject object, a general-purpose properties holder
  • SPPropsSchema - Creates a new, empty SPPropsSchema object. This is used to define the contents, display or access properties of an SPPropsObject
  • SPPropsSchemaItem - Creates a new, empty SPPropsSchemaItem object. This defines a single element in SPPropsSchema
  • SPRect - Creates a new SPRect object, used to represent a graphical rectangle with coordinates left, top, right and bottom
  • SPRichConsole - Creates a new SPRichConsole object which is used to display a scrolling console window with rich text capabilities.
  • sprintf - Generates formatted text output to a string.
  • SPStringMap - Creates a new SPStringMap object.
  • SPXMLFile - Creates a new SPXMLFile object which can be used to read and parse an arbitrary XML ile.
  • SPXMLText - Creates a new SPXMLText object which can be used to read and parse an arbitrary string of XML text.
  • SPZip - Creates a new SPZip object.
  • write - Writes text to the console window.
  • writeFile - Writes binary or text data to a file.
  • writeln - Writes text to the console window followed by a newline.
  • Method: addScriptSearchPath

    Adds a new directory to the list of the directories that will be searched for scripts whenever a script file name is specified.

    void addScriptSearchPath(pathString);

    void addScriptSearchPath(pathString, permanent);

    Parameters
    Name Expected Type Description
    permanent Boolean specifies whether this setting should be "permanent", i.e. the settings should be saved by the application and restored automatically each time the application is started. If this is false, the settings remain in effect only until the application quites. Defaults to true.
    pathString String a single directory name. This may be an absolute or relative path. If it is relative, the standard application directories are searched for the directory.

    Method: alert

    This displays a simple box with an OK button and the given string.

    void alert(textString);

    Parameters
    Name Expected Type Description
    textString String The text to display.

    Method: appendFile

    Works identically to writeFile except that data is appended to an existing file, instead of replacing it.

    Remarks:

    This method is useful as a method of logging errors or actions during script execution. If the file doesn't exist, it is created.

    See Also:

  • writeFile
  • Method: assert

    This displays a simple box with an OK button and the given string.

    void assert(condition, textString);

    Parameters
    Name Expected Type Description
    textString String The text to display if condition is not met
    condition bool Condition which should normally be true

    Method: command

    Runs the given DOS-style command.

    String command(commandStr);

    String command(commandStr, waitMillis);

    Parameters
    Name Expected Type Description
    waitMillis int The amount of time to wait for completion of the command. If this is not specified, or a negative value is given, it waits until the started command completes, regardless of how long that takes. If zero is given, it returns immediately. If a positive value is given, it waits for the command to complete, or for the given number of milliseconds, whichever comes first.
    commandStr String The command string to execute

    Remarks:

    This function starts the DOS command interpreter and submits the given command. On Windows NT systems only, the function returns a string containing the output from the command. Note that the command processor is started from scratch each time this function is used, so it has no memory of current drive or directory settings. All commands and file names should be specified with complete paths.

    Method: compareBinary

    Compares two data items for an exact binary equivalence. This can be used to verify an exact copy after file or network operations.

    void compareBinary(block1, block2);

    Parameters
    Name Expected Type Description
    block1 array/string First data item for comparison
    block2 array/string Second data item for comparison

    Returns:

    bool - true if the two blocks match exactly, false otherwise

    Errors:

    Will generate an exception if the two arguments don't match and no return value is requested. See the remarks.

    Remarks:

    Note that you can use this function with no return value, as in the following example. In this case, the script will halt with an error if the blocks don't match. This can be used to do a quick and dirty comparison without bothering with a fancy error response.

    Example:

    // Write a file, then read it back and compare.
    // This will generate an exception if the two
    // files are not identical.
    
    data1 = SPFile("c:/source.dat").readBinary();
    SPFile("c:/dest.dat").writeBinary(data1);
    compareBinary(SPFile("c:/dest.dat").readBinary(), data1);
    

    Method: confirm

    This displays a simple box with OK and Cancel buttons and the given string.

    bool confirm(textString);

    Parameters
    Name Expected Type Description
    textString String The text to display.

    Returns:

    Returns true if OK clicked, false if Cancel clicked.

    Method: convertCRLF

    Converts the given string from internal LF-only to Windows-style CR/LF line termination.

    String convertCRLF(text);

    Parameters
    Name Expected Type Description
    text String The text to convert.

    Returns:

    Returns a new string with all lines terminated with carriage return/line feed.

    Remarks:

    This should only be used in rare cases where an ActiveX control or other external object requires Windows-style line termination and will not accept a multiline string passed directly. This method is not required when writing to a file or FTP site using "writeText" methods since the conversion is done automatically.

    Method: ConvertSlashes

    Gets or sets the status of the global "convert slashes in filenames" flag.

    bool ConvertSlashes();

    void ConvertSlashes(flagValue);

    Parameters
    Name Expected Type Description
    flagValue bool true to enable slash conversion, false to disable it.

    Remarks:

    If this flag is on, all methods and functions that operate on file names will accept a "/" forward slash character as a directory separator. This allows easier specification of path names without having to escape every backslash character that is used in a JavaScript string constant.

    Method: createDirectory

    Creates the specified directory.

    bool createDirectory(pathStr);

    Parameters
    Name Expected Type Description
    pathStr String The full path of the directory to create

    Remarks:

    This function will do its best to create the given path, creating all the parent directories if necessary. If the given directory already exists, nothing is done and no error is reported.

    Method: decrypt

    Decrypts the given data and returns a new array containing the decrypted block.

    Array decrypt(passwordStr, data);

    Parameters
    Name Expected Type Description
    passwordStr String The password used to encrypt the data.
    data data This is the encrypted binary data block. This must be exactly the block generated by encrypt with no modifications of any kind.

    Returns:

    Returns the decrypted data. Most data types, including strings, will be decrypted back to the data type they existed in before they were encrypted.

    Remarks:

    This decrypts the given data block that was encrypted using encrypt.

    Method: deleteDirectory

    Deletes the given directory, including all its contents.

    bool deleteDirectory(pathStr);

    Parameters
    Name Expected Type Description
    pathStr String The full path of the directory to delete

    Remarks:

    WARNING: This will delete the given directory and everything in it without comment!!! There is no way of undoing this operation once it is done.

    Method: deleteFile

    Deletes the specified file.

    bool deleteFile(pathStr);

    Parameters
    Name Expected Type Description
    pathStr String The full path name of the file to delete

    Method: deleteFiles

    Deletes all files and directories matching the given pattern.

    bool deleteFiles(patternStr);

    bool deleteFiles(patternStr, except);

    Parameters
    Name Expected Type Description
    except String A file name to omit from the delete process, not including its path.
    patternStr String The full path name and pattern specifying the files to delete. See the examples.

    Example:

    deleteFiles("c:/images/*.gif");                 // Delete all files with the given extension
    deleteFiles("c:/data/item*.dat", "item9.dat");   // Delete all "itemxxx.dat" except item9.dat
    deleteFiles("c:/*.*");                          // Delete the entire contents of you c: drive!!! (No I haven't tested it!)
    

    Method: encrypt

    Encrypts the given data and returns a new array containing the encrypted block.

    Array encrypt(passwordStr, data);

    Parameters
    Name Expected Type Description
    passwordStr String The password used to encrypt the data. The longer the better!
    data data The data to encrypt. This can be any data type that can be converted to a binary array.

    Returns:

    Returns the encrypted data as an array of bytes.

    Remarks:

    This encrypts the given data using a 40-bit algorithm and returns the result as a binary data block. This block can then be written to a file or transmitted by FTP as desired. Passing a complex object to this function will result in the objects "value" method being called and the resulting data being encrypted. In general, this will not result in the object being reconstituted when it is decrypted.

    Method: getAppDataDir

    Gets the directory path of the user's application data directory, i.e. the default location where temporary and writeable program data files are stored.

    String getAppDataDir();

    Returns:

    The directory path string

    Method: getAppDir

    Gets the directory path of the application, i.e. the location where the main application is stored.

    String getAppDir();

    Returns:

    The directory path string

    Method: getDocRootDir

    Gets the directory path of the document root directory, i.e. the default location where user files are stored.

    String getDocRootDir();

    Returns:

    The directory path string

    Method: getEnv

    Gets the value of a system environment variable.

    value = getEnv(name);

    Parameters
    Name Expected Type Description
    name String The name of the desired environment variable.

    Returns:

    Returns the value string, or null if no environment variable was found with the given name.

    Example:

    paths = getEnv("PATH");
    

    Method: getFileList

    Generates a list of files in the given directory.

    Array getFileList(directoryPath);

    Array getFileList(directoryPath, patternStr);

    Array getFileList(directoryPath, patternStr, inclDir);

    Array getFileList(directoryPath, patternStr, inclDir, hier);

    Parameters
    Name Expected Type Description
    directoryPath String String specifying the full path to the directory in question. As with other file specifications, directory names can be separated with either forward "/" or backward "\" slashes
    inclDir bool True to include sub-directories in the file list, true by default
    hier bool True to generate a hierarchical list of files, that is, the file list will contain entries for all files in all sub-directories found. The list will not contain any intermediate directories. False by default.
    patternStr String Optional pattern to match a subset of the files in the directory, e.g. "*.doc". If this is not specified, all files in the directory match.

    Returns:

    Returns an array of SPFile objects, one for each item matched. The methods in the SPFile object can be used to read, write or get information about the individual files.

    Errors:

    Does not generate any error exceptions. If the given directory doesn't exist or can't be read for any reason, an empty array is returned.

    Example:

    files = getFileList("c:/temp");
    writeln("These are the temporary files:");
    for (i = 0; i < files.length; i++)
    {
        printf("File #%08d is %s", i, files[i].fullName);
    }
    

    See Also:

  • SPFile
  • Method: getGlobalNames

    Returns an array list of the names of all currently set global values

    SPArray getGlobalNames();

    Method: getGlobalValue

    Gets a value stored in a global object

    value = getGlobalValue(name);

    Parameters
    Name Expected Type Description
    name string A "variable name" that the value was saved under. This is case sensitive and there are no restrictions on length or character content of the name

    Returns:

    Returns the saved value, or null if there is no value under the given name

    Remarks:

    This function is used in conjunction with setGlobalValue to save arbitrary values that can be used by other system components by other other invocations of scripts. These values are global to the application and survive for the application session.

    NOTE: You can also get and set values by direct reference to a name, as in
    valName = newValue; // Set the value
    prevValue = valName; // Get the value
    Any unknown name will automatically get added to the list of known top-level symbols.

    WARNING: Is is very risky to globally save objects such as DesignWorks circuit elements or any other objects that may refer to outside resources. Such objects may contain internal pointers that may be invalidated by other application operations and may cause the program to crash if misused. The only safe use of this function is to store simple numerical or string values.

    Example:

    prevSetting = getGlobalValue("OldSetting");
    

    See Also:

  • setGlobalValue
  • Method: getIniDirs

    Gets a list of the directories specified as a keyword in the INI file(s)

    String = getIniDirs(section, name);

    Parameters
    Name Expected Type Description
    section String The name of the ini file section to read
    name String The name of the item to read

    Returns:

    Returns an SPArray object containing full path names for all directories specified in all matching keywords

    Remarks:

    The directories are evaluated relative to the location of the INI file containing the keyword. Any contained path variables are evaluated, e.g. %my documents%

    Method: getIniItem

    Gets the value of an item in the application ini (initialization) file

    String = getIniItem(section, name);

    Parameters
    Name Expected Type Description
    section String The name of the ini file section to read
    name String The name of the item to read

    Remarks:

    Quotation marks are stripped from any string values

    Method: getPublicDataDir

    Gets the directory path of the public program data directory, i.e. the default location where temporary and writeable program data files are stored that is accessible to all users. Under Windows XP, this usually the "All Users" user folder, under Vista, this will be the hidden "ProgramData" folder.

    String getPublicDataDir();

    Returns:

    The directory path string

    Method: getRandomInt

    Returns a random integer in the given range

    int getRandomInt(min, max);

    Parameters
    Name Expected Type Description
    max int The highest number that will be returned
    min int The lowest number that will be returned

    Method: getScriptArg

    Gets the value of a positional argument passed when the script was invoked.

    value = getScriptArg(num);

    Parameters
    Name Expected Type Description
    num int The argument number, in the range 1 to N, where N is the number of arguments passed.

    Returns:

    Returns the argument value string, or null if no argument with the given number.

    Remarks:

    This function is used to fetch argument values that were passed by the outside caller that invoked the script. For example, if the script was started directly from the application's command line, the arguments given after the script name can be accessed by this method.

    Example:

    secondArg = getScriptArg(2);
    

    Method: getScriptSearchPaths

    Gets a list of the directories that will be searched for scripts whenever a script file name is specified.

    SPArray getScriptSearchPaths();

    Returns:

    Returns an SPArray object containing path strings. The number of items can be determined using the SPArray.length property.

    Remarks:

    Returns a list of all current script search paths, including those set permanently in the application's initialization file and others added later by the user or by scripts.

    Method: getStateItem

    Gets the value of an item in the application state file

    String = getStateItem(section, name);

    Parameters
    Name Expected Type Description
    section String The name of the state file section to read
    name String The name of the item to read

    Remarks:

    Quotation marks are stripped from any string values

    Method: getTextFromClipboard

    Returns a string containing any text on the clipboard.

    String getTextFromClipboard();

    Returns:

    A string containing any text present on the clipboard, or null if there is no text available.

    Method: getTickCount

    Gets the system tick count, i.e. the time in milliseconds since the system was last restarted. The value is returned as a double.

    double getTickCount();

    Method: getWordsFromText

    Version added: 1.2

    Creates an array of the "words" in a text string.

    SPArray getWordsFromText(text);

    SPArray getWordsFromText(text, charSet);

    Parameters
    Name Expected Type Description
    charSet String A string containing one each of all the characters allowed in a word. If this is not specified, the upper and lower case letters are assumed.
    text String The source text from which words are to be extracted

    Remarks:

    This function returns an SPArray object containing all the words extracted from the text, in the exact order found. Duplicates are not removed, although they can easily be removed using SPArray.removeDuplicates. A "word" consists of any sequence of the characters found in the character set, and a word ends when any character not in the set is encountered. If no words are located an array of length zero will be returned.

    Method: halt

    Immediately stops execution of the script.

    void halt();

    void halt(messageStr);

    Parameters
    Name Expected Type Description
    messageStr String A text message to display in the exception error box.

    Remarks:

    If any string argument is given, an exception error box is displayed with the given string, otherwise no box is displayed.

    Method: htmlProperties

    This displays a property page with individual sheets defined using HTML.

    String htmlProperties(urls);

    String htmlProperties(urls, defaultVals);

    String htmlProperties(urls, defaultVals, title);

    String htmlProperties(urls, defaultVals, title, sizeX, sizeY);

    Parameters
    Name Expected Type Description
    title String The title for the dialog box
    defaultVals SPArray The default values to place in the controls on the pages. This can be an array of strings to match the controls on the pages.
    sizeX int The width in pixels for the displayed box. If not specified, defaults are used.
    sizeY int The height in pixels for the displayed box
    urls String The URL(s) or file name(s) of the HTML page(s) to display. If this is a string, then a simple dialog box is displayed showing that page. If this is an SPArray of strings, then a tabbed property sheet box is displayed with one tab per URL.

    Returns:

    Returns an array of the control values if OK clicked, null if Cancel clicked. The form of this array is the same as the defaultVals array passed as an argument.

    Property: isUserAdmin

    Returns true if the current computer user has system administrator privileges.

    bool isUserAdmin();

    Method: loadVar

    Version added: 1.1

    Loads a variable value that was saved using saveVar.

    value loadVar(name);

    Load the value with the given name. If the value doesn't exist, "null" is returned.

    value loadVar(name, default);

    Load the value, or return the default value if not found.

    Parameters
    Name Expected Type Description
    default data A default value to return if the given name is not found.
    name String The variable name. See comments under saveVar.

    Errors:

    An exception will be generated if the data is found but is corrupt or an unrecognized format.

    Method: locateScriptFile

    Find a file using the default script search paths

    value locateScriptFile(fileName);

    Parameters
    Name Expected Type Description
    fileName String The name or relative path of a file to be located

    Remarks:

    If the file name string does not contain an absolute path, then the directory containing the current script is searched first, followed by the script search paths, followed by the application directory and any other search paths specified by the application.

    Method: makeSafeXMLString

    Converts the given string to a string that is safe to include as a string constant in an XML (or HTML) file

    string makeSafeXMLString(srcStr);

    Parameters
    Name Expected Type Description
    srcStr string The source string to convert

    Returns:

    Returns the converted string

    Remarks:

    This method returns a string that is compatible with 8-bit ANSI files, i.e. any Unicode characters with code >255 are converted to hex constants

    Method: navigate

    Start the default Web browser and pass it the given URL

    void navigate(urlString);

    Parameters
    Name Expected Type Description
    urlString String The URL to navigate to

    Method: NetPadFile

    Creates a new NetPadFile object.

    NetPadFile NetPadFile();

    // Creates a NetPadFile object without any file association

    NetPadFile NetPadFile(filePath);

    // Creates a NetPadFile object associated with the given file

    Parameters
    Name Expected Type Description
    filePath String The complete path name of the NetPad file. The file does not have to exist initially. It can be created using the NetPadFile.create method. If this is not specified, the NetPadFile object will be unassociated initially and a file name must be set before it can be used.

    See Also:

  • NetPadFile
  • Method: parseScriptFile

    This is the same as parseScriptText but the source is a file instead of a literal string.

    value parseScriptFile(fileName);

    Parameters
    Name Expected Type Description
    fileName String The name of a file containing the text to be parsed.

    Remarks:

    If the file name string does not contain an absolute path, then the directory containing the current script is searched first, followed by the application directory and any other search paths specified by the application.

    Method: parseScriptText

    Parses the given string as if it was part of the current script. Any global objects and methods in the current script are accessible to the new script and any top level items defined in the new script will be accessible to the calling script. Any top level statements in the added script are executed immediately. If any one of these statements is an expression that generates a value, that value is returned.

    value parseScriptText(text);

    Parameters
    Name Expected Type Description
    text String The script text to be parsed.

    Returns:

    Returns the value produced by the last top level expression executed in the given script.

    Method: printf

    Generates formatted text output to the console window.

    void printf(formatStr, arg1, ...);

    Parameters
    Name Expected Type Description
    arg1... data Values to be converted to text according to the format commands in the format string
    formatStr String Text string containing literal text and format arguments

    Returns:

    void

    Errors:

    Does not generate any error exceptions. If the actual arguments don't match the data required by the format string, default values will be substituted in the output.

    Remarks:

    This method is used to generate formatted text in the console window using format arguments patterned after the standard C/C++ printf function. Since the formatting arguments are quite extensive, they are described on a separate page printf Formatting. Users familiar with the original C function should note that JavaScript conversions are considerably more general than C. For example, essentially any JavaScript data item can be converted to a string, so "%s" conversion can be used with any data argument to get a default output.

    Example:

    files = getFileList("c:/temp");
    writeln("These are the temporary files:");
    for (i = 0; i < files.length; i++)
    {
        printf("File #%08d is %s", i, files[i].fullName);
    }
    

    See Also:

  • sprintf
  • SPFile.fprintf
  • Method: progress

    Writes text to the application's status bar progress box

    void progress(textStr);

    Parameters
    Name Expected Type Description
    textStr String The text to display.

    Method: prompt

    This displays a simple box with OK and Cancel buttons and one or more text entry boxes.

    String prompt(labelText);

    String prompt(labelText, defaultText);

    String prompt(labelText, defaultText, title);

    Parameters
    Name Expected Type Description
    title String The title for the dialog box
    defaultText String The default text to place in the edit box. This can be an array of strings to match the edit boxes created as noted above.
    labelText String The label text to display next to the edit box. If this is a string, then a single edit box is displayed. If this is an SPArray of strings, then multiple edit boxes are displayed, one per element.

    Returns:

    Returns the string or strings entered if OK clicked, null if Cancel clicked. If only a single edit box is created (i.e. "labelText" is a simple string or an array of one element), then the return value is a string. If multiple boxes are created (i.e. "labelText" is an array), then an SPArray of values is returned, one per edit box.

    Method: putTextOnClipboard

    Places the given text on the clipboard.

    bool putTextOnClipboard(text);

    Parameters
    Name Expected Type Description
    text String The text to place on the clipboard

    Returns:

    true if OK, false if any error (very unlikely).

    Method: run

    Runs an application or opens a file. This is equivalent to double-clicking on the specified file in the Explorer. If the file is an application, it is started. If the file is a document, the system attempts to find the associated application and open it.

    bool run(fileName);

    bool run(fileName, arguments);

    bool run(fileName, arguments, startingDir);

    bool run(fileName, arguments, startingDir, waitMillis);

    Parameters
    Name Expected Type Description
    startingDir string The initial default directory for the application. This is ignored if the specified file is not an application.
    fileName string The complete path of the application or file in question.
    arguments string The command line arguments to pass to the application. This is ignored if the specified file is not an application.
    waitMillis int The amount of time to wait for completion of the other application. If this is not specified, or zero is given, the call returns immediately without waiting for completion. If a negative value is given, it waits until the started application completes, regardless of how long that takes. If a positive value is given, it waits for the application to complete, or for the given number of milliseconds, whichever comes first.

    Returns:

    Returns true if the command was completed, false if it was still running on return.

    Method: saveVar

    Version added: 1.1

    Saves a variable value to the system registry.

    void saveVar(name);

    Save a boolean "true" value.

    void saveVar(name, value);

    Save the given value.

    Parameters
    Name Expected Type Description
    value data The data to save. This must be a simple object (i.e. scalar, string or byte array) and must not exceed 1K (1024 bytes) in size.
    name string The variable name. See comments below.

    Errors:

    An exception will be generated for any attempt to save any data this is too long or an unsupported data type.

    Remarks:

    This function saves a variable to the system registry so that's its value can be used in later executions of the same, or any other, script.

    Variable names are universal, i.e. any script in any script database file on the same computer can request or change the value using the same name at any future time. Variable names are also hierarchical, i.e. you can create groups of variables by using a "path" format similar to a file name. For example:

    saveVar("FileCleanUp/LastFile", lastFileName);
    will create a registry key called "FileCleanUp" and under it a variable called "LastFile". This can be used to group values with a common function. Any number of nested names can be used.

    saveVar cannot save complex system or user-defined objects such as arbitrary arrays, Date, SPInternet, etc. Special handling is included for SPArray objects with binary values, but other types of objects must be converted to some suitable binary or string value in order to be saved. This restriction is necessary because of the arbitrary complexity of the internal storage and state of these objects.

    If you need to get direct access to values saved with saveVar using other registry tools, they are stored under the key HKEY_CURRENT_USER\Software\FlyingObjects\ScriptPilot\UserVars. Values are stored with a header that specifies the length and type of data so that it can be reconstructed with its original data type. This data should not be hand modified unless you're sure you know what you're doing!

    Method: setGlobalValue

    Saves an arbitrary value to a global object

    void setGlobalValue(name, value);

    Parameters
    Name Expected Type Description
    value value Any value. See below for warnings about this value.
    name string A "variable name" that the value will be saved under. This is case sensitive and there are no restrictions on length or character content of the name

    Remarks:

    This function is used in conjunction with getGlobalValue to save arbitrary values that can be used by other system components by other other invocations of scripts. These values are global to the application and survive for the application session.

    WARNING: Is is very risky to globally save objects such as DesignWorks circuit elements or any other objects that may refer to outside resources. Such objects may contain internal pointers that may be invalidated by other application operations and may cause the program to crash if misused. The only safe use of this function is to store simple numerical or string values.

    Example:

    setGlobalValue("OldSetting", boxValue);
    

    See Also:

  • getGlobalValue
  • Method: setScriptResult

    Set the script result value that will be returned to the process that invoked the script

    void setScriptResult(text);

    void setScriptResult();

    Parameters
    Name Expected Type Description
    text String The text value to return to the caller. The argument does not have to be a string, but it will be converted to a string value before being returned. If this parameter is omitted, the existing return value is cleared, so any natural return value from the script will be received

    Remarks:

    If a value is set using this method, this value will override any value returned by the script itself

    Method: setScriptSearchPaths

    Sets the list of the directories that will be searched for scripts whenever a script file name is specified.

    void setScriptSearchPaths(pathString);

    void setScriptSearchPaths(pathsArray);

    void setScriptSearchPaths(pathString, permanent);

    void setScriptSearchPaths(pathsArray, permanent);

    Parameters
    Name Expected Type Description
    permanent Boolean specifies whether this setting should be "permanent", i.e. the settings should be saved by the application and restored automatically each time the application is started. If this is false, the settings remain in effect only until the application quites. Defaults to true.
    pathsArray SPArray an array containing any number of directory path strings. They will be searched in the order given.
    pathString String a single directory name. This may be an absolute or relative path. If it is relative, the standard application directories are searched for the directory.

    Remarks:

    This method removes all search directories currently on the search path list, except "hard" settings that are specified in the application's initialization file, and then adds the given item or items.

    Method: setStateItem

    Sets the value of an item in the application state file

    void setStateItem(section, name, value);

    Parameters
    Name Expected Type Description
    value String The new value for the item
    section String The name of the state file section to read
    name String The name of the item to read

    Method: sleep

    Pauses execution of the script for the given number of milliseconds.

    void sleep(waitMillis);

    Parameters
    Name Expected Type Description
    waitMillis int The amount of time to sleep, in milliseconds.

    Method: SPArray

    Version added: 1.1

    Creates a new SPArray object, optionally containing some initial data.

    SPArray SPArray();

    Initializes an empty array

    SPArray SPArray(multiLineString);

    Extracts lines from the given string and makes them elements

    SPArray SPArray(str1, ...);

    Converts each argument to a string and makes it an element

    Parameters
    Name Expected Type Description
    multiLineString string A string that will be used to initialize the array. Substrings separated by newline characters will be placed in successive elements.
    str1 string Any number of strings to be assigned to assigned to array elements.

    Remarks:

    This function with no arguments creates a new, empty SPArray object. It will rarely be necessary to use this function. Normally, an SPArray object is created by a function that returns one, such as getFileList. In some cases, such as the following example, it may be desirable to create an empty array initially for later modification.

    NOTE: Remember that the SPArray object differs from the standard JavaScript Array object in that all elements must be of the same type. Three types are supported, binary (i.e. an array of bytes), string and object.

    Example:

    a = SPArray();
    addFiles(a, "c:/documents");
    addFiles(a, "c:/development");
    
    function addFiles(arr, dir)
    {
        arr.append(getFileList(dir));
    }
    

    See Also:

  • SPArray
  • Method: SPColour

    Creates an SPColour object, which represents a colour for display graphics operations

    Method: SPDatabase

    Creates a new SPDatabase object.

    SPDatabase SPDatabase(fileName);

    Parameters
    Name Expected Type Description
    fileName string The complete path and name of the database file to associate with this object.

    Returns:

    Returns the SPDatabase object. This only creates the object and a non-null value does not mean the database was opened successfully.

    See Also:

  • SPDatabase
  • Method: SPDatastash

    Creates a new SPDatastash object.

    SPDatastash SPDatastash();

    SPDatastash SPDatastash(fileName, ...);

    Parameters
    Name Expected Type Description
    fileName String The name of the database file to open

    See Also:

  • SPDatastash
  • Method: SPFile

    Creates a new SPFile object.

    SPFile SPFile();

    SPFile SPFile(fileName);

    SPFile SPFile(fileName, refDir, ...);

    Parameters
    Name Expected Type Description
    refDir String If the file name given is relative, this directory will be searched first for the given file, before looking in the usual system locations. Any number of additional refDir arguments can be specified
    fileName String A full or relative path and name of the file to associate with this object. If this is not specified, the file object will be unassociated and the path must be set before it is used.

    See Also:

  • SPFile
  • Method: SPHTMLDialog

    Creates a new, empty SPHTMLDialog object which is used to display an HTML dialog or property sheet.

    SPHTMLDialog SPHTMLDialog();

    See Also:

  • SPHTMLDialog
  • Method: SPPoint

    Creates a new SPPoint object, used to represent a graphical point with coordinates X and Y

    SPPoint SPPoint();

    SPPoint SPPoint(x, y);

    SPPoint SPPoint(point);

    Parameters
    Name Expected Type Description
    point SPPoint An existing SPPoint object, whose values will be copied
    y real A numeric value for the initial Y coordinate, may be integer or real
    x real A numeric value for the initial X coordinate, may be integer or real

    Method: SPPropsObject

    Creates a new, empty SPPropsObject object, a general-purpose properties holder

    SPPropsObject SPPropsObject();

    See Also:

  • SPPropsObject
  • Method: SPPropsSchema

    Creates a new, empty SPPropsSchema object. This is used to define the contents, display or access properties of an SPPropsObject

    SPPropsSchema SPPropsSchema();

    SPPropsSchema SPPropsSchema(name);

    Parameters
    Name Expected Type Description
    name String The name of the desired schema. This will be matched against available schemas in predefined locations. This may return null if no match is found.

    See Also:

  • SPPropsSchema
  • Method: SPPropsSchemaItem

    Creates a new, empty SPPropsSchemaItem object. This defines a single element in SPPropsSchema

    SPPropsSchemaItem SPPropsSchemaItem();

    See Also:

  • SPPropsSchemaItem
  • Method: SPRect

    Creates a new SPRect object, used to represent a graphical rectangle with coordinates left, top, right and bottom

    SPRect SPRect();

    SPRect SPRect(l, t, r, b);

    SPRect SPRect(rect);

    Parameters
    Name Expected Type Description
    l real A numeric value for the initial left coordinate, may be integer or real
    rect SPRect An existing SPPoint object, whose values will be copied
    t real A numeric value for the initial top coordinate, may be integer or real
    b real A numeric value for the initial bottom coordinate, may be integer or real
    r real A numeric value for the initial right coordinate, may be integer or real

    Method: SPRichConsole

    Creates a new SPRichConsole object which is used to display a scrolling console window with rich text capabilities.

    SPRichConsole SPRichConsole();

    SPRichConsole SPRichConsole(title);

    SPRichConsole SPRichConsole(title, alias);

    Parameters
    Name Expected Type Description
    title string The displayed window title
    alias string The window alias, i.e. an internally used name that is used to connect to the window. If a console window already exists with the same alias, this new object will connect to the existing window rather than creating a new one. If this is not specified, a new window is always created.

    See Also:

  • SPRichConsole
  • Method: sprintf

    Generates formatted text output to a string.

    String sprintf(formatStr, arg1, ...);

    Parameters
    Name Expected Type Description
    arg1... data Values to be converted to text according to the format commands in the format string
    formatStr String Text string containing literal text and format arguments

    Returns:

    Returns the formatted string.

    Errors:

    Does not generate any error exceptions. If the actual arguments don't match the data required by the format string, default values will be substituted in the output.

    See Also:

  • printf
  • SPFile.fprintf
  • Method: SPStringMap

    Creates a new SPStringMap object.

    SPStringMap SPStringMap();

    See Also:

  • SPStringMap
  • Method: SPXMLFile

    Creates a new SPXMLFile object which can be used to read and parse an arbitrary XML ile.

    SPXMLFile SPXMLFile();

    SPXMLFile SPXMLFile(fileName);

    SPXMLFile SPXMLFile(fileName, refDir, ...);

    Parameters
    Name Expected Type Description
    refDir String If the file name given is relative, this directory will be searched first for the given file, before looking in the usual system locations. Any number of additional refDir arguments can be specified
    fileName String A full or relative path and name of the file to associate with this object. If this is not specified, the file object will be unassociated and the path must be set before it is used.

    Method: SPXMLText

    Creates a new SPXMLText object which can be used to read and parse an arbitrary string of XML text.

    SPXMLText SPXMLText();

    SPXMLText SPXMLText(text);

    Parameters
    Name Expected Type Description
    text String If given, the XML text to be assigned to this object

    Method: SPZip

    Creates a new SPZip object.

    SPZip SPZip(fileName);

    Parameters
    Name Expected Type Description
    fileName string The complete path and name of the zip file to associate with this object. The file does not have to exist.

    See Also:

  • SPZip
  • Method: write

    Writes text to the console window.

    void write(textStr);

    Parameters
    Name Expected Type Description
    textStr String The text to display.

    Method: writeFile

    Writes binary or text data to a file.

    void writeFile(fileName, array);

    void writeFile(fileName, string);

    Parameters
    Name Expected Type Description
    string string Text data to be written out.
    fileName string Complete file name, including path. Forward slashes are converted to backslashes in file names.
    array array Binary data to be written out.

    Returns:

    void

    Remarks:

    WARNING: If the specified file already exists, it is replaced without comment. Generates an exception if any error occurs. For more complete error handling, use the read/write methods in the SPFile object. If the data argument is a string data type, text conversion is done on the data so that the resulting file is stored in ASCII character codes with CR/LF line terminators. If you don't want this conversion, use SPFile.writeBinary.

    Example:

    str = "hello\n";
    writeText("c:/hello.txt", str);
    

    See Also:

  • SPFile.writeText
  • Method: writeln

    Writes text to the console window followed by a newline.

    void writeln(textStr);

    Parameters
    Name Expected Type Description
    textStr String The text to display.