IDE Script

Used in the IDE to script the development environment.

# Notes

# Commands

Here is the list of IDE scripting commands.

Name | Type | Parameters | Description
--- | --- | --- | ---
Beep |  |  | Plays the system beep.
BuildLanguage | String |  | Gets or sets the current build language.
BuildLinux | Boolean |  | Gets or sets whether to build for the Linux platform.
BuildMacClassic | Boolean |  | Gets or sets whether to build for the Mac OS classic platform.
BuildMacMachO | Boolean |  | Gets or sets whether to build a Mach-O Macintosh application.
BuildMacPEF | Boolean |  | Gets or sets whether to build a PEF Macintosh application.
BuildRegion | String |  | Gets or sets the region code to be used in the built application.
BuildWin32 | Boolean |  | Gets or sets whether to build for the Windows platform.
Clipboard | String |  | Gets or sets the contents of the copy/paste buffer, aka "clipboard."
DoCommand |  | cmdName as String | Executes the passed command, as if the user had pressed the corresponding toolbar button or chosen the corresponding menu item. Every such command in the IDE has a unique name which is used as the argument for DoCommand. To find the name of a particular command, use the script recording feature.
DoShellCommand | String | cmd as String, timeout as Integer | Executes the passed shell command. The shell environment is set up with the following variables: IDE_PATH to point to the directory containing the IDE; PROJECT_PATH to point to the directory containing the project in the frontmost window; and PROJECT_FILE to point to the actual project file. The command is executed in synchronous (blocking) mode, and returns any output as the result. The default value for timeout is 3000.
EndOfLine | String |  | Returns the default line ending for the platform on which the application is running. This is also the line separator in source code text, i.e., that returned by Text and SelText.
Location | String |  | Gets or sets the current location of the project, as shown in the Location field in the Main Toolbar. A script can use this both to see its current location and to navigate to another part of the project.
OpenFile |  | path as String | Attempts to open a REALbasic project file specified by the passed path. This can be either a native or shell path.
ProjectItem | String |  | Returns the name of the current project item, that is, the project item that is currently being edited or is selected in the IDE tab bar.
PropertyValue |  | propName as String | Gets or sets the value of a project name property. The propName argument may be just the property name, in which case the property is found on the current project item; or it may be the name of a project item plus the property name, separated by a dot. You may also use the special keyword "App" to refer to the blessed Application subclass, even if that is not actually named App. The following are all valid property references: "Width", "Window1.Width", "App.MajorVersion".
RunScript |  | scriptName as String | Runs the passed script, found in the Scripts folder, either next to the IDE or next to the frontmost project file.
SelectWindow |  | windowTitle as String | Brings the passed window to the front. If there is more than one window named windowTitle, then the one closest to the front is the one brought to the front.
SelectWindow |  | Index as Integer | Brings a window to the front identified by its current index in the Window list (see the WindowCount and WindowTitle functions).
SelLength | Integer |  | Gets or sets the length in characters of the current selection in the current Code Editor, assuming that there is a selection.
SelStart | Integer |  | Gets or sets the offset of the selection or insertion point in the current Code Editor.
SelText | String |  | Gets or sets the selected text in the current Code Editor. Note that after assigning to SelText, the selection will be empty and positioned right after the inserted text. (This is the same behavior as EditField.SelText.)
Speak |  | text as String, Interrupt as Boolean | Speaks the passed text via the system's speech synthesis engine. The default value of Interrupt is False. If interrupt is set to True, then it interrupts any previous speech. Otherwise, it waits for the previous speech to finish. This is the same behavior as the built-in Speak command.
Sublocations |  | baseLocation as String | Returns all the locations within the given base location as a space-delimited string. For example, if baseLocation is "App", then this might return "App.Activate App.CancelClose App.Close" (and so on). The set of locations returned should be the same ones suggested by autocompletion in the Location field within the IDE. If baseLocation is an empty string, then this returns the set of project items in the frontmost project.
Text | String |  | Gets or sets the entire text of the current Code Editor.
WindowCount | Integer |  | Returns the number of windows in the IDE.
WindowTitle | String | index as Integer | Returns the title of a window indicated by the passed Index in the window list. An index of zero is the frontmost window.

The REALbasic IDE has its own RBScript editor that you can use to automate many aspects of the development process. Choose File . IDE Scripts . New IDE Script to access this code editor. You can write scripts manually or turn on the "record" feature to record your actions within the IDE. Once you are in record mode, click Record again to stop recording. Every menu item and toolbar button has a command name that can be called from an IDE script via the DoCommand command. If you have saved scripts, they are added to the IDE Scripts submenu. You can save a script via the IDE Script editor's File . Save As command or you will be given a chance to save your script when you close the IDE Script editor window.

In order for saved scripts to appear in the IDE Scripts submenu, they must be stored in a folder called "Scripts" that can be either in the same folder as the IDE or the same folder as the current project.

## Recording

When you click the Record button in the IDE Script editor, the editor goes into "recording" mode and the button stays down as long as it's in this mode. While recording, any scriptable action you do in the IDE is added to the editor as RBScript code. You then return to the Script editor, stop the recording by clicking the Record button again, and edit the script -- deleting unimportant commands, changing constants to variables as required, and so on.

Use the record feature to get the names of commands to pass to the DoCommand method.

Script recording is a powerful feature for automating repetitive tasks; it does most of the work for you, freeing you from having to know the syntax for most actions.

Your scripts have access to all the standard functions in RBScript, including string manipulation, math, and so on. The RBScript Print command displays a message box, and the Input command gets input via a simple modal dialog. As in any RBScript, you can also write methods, classes, or modules within your script if needed to help organize your code (though many scripts will be so simple as to not need them).

## IDE Scripting Commands

In addition to the standard RBScript functions, there are additional functions and properties that are defined only for IDE scripts which manipulate projects in the IDE in various ways. These functions are described in the Commands table. Most of them operate on the frontmost Project Window and on the current project item or method within that window. However, there are ways to change the current window or location for cases where your script needs to act upon a particular item.

Most of the things your script can do fall into one of the following categories and use the indicated RBScript commands:

Changing the context (SelectWindow, Location)

Changing project item properties (PropertyValue)

Changing build settings (BuildLanguage, BuildLinux, BuildMacMachO, etc.)

Executing commands, as if chosen from a toolbar or menu (DoCommand)

Interacting with the user (Print, Input, Beep, Speak)

Inspecting or changing source code (Text, SelText, SelStart, SelLength)

There are also a few utility functions that don't fit neatly into the above categories (e.g., Clipboard).

# Examples

The following script issues the traditional greeting via a MsgBox:

Print "Hello world!"

This script sets the ShortVersion to "1.0J", sets the build language to Japanese, and then builds a Mac version of the application:

PropertyValue("App.ShortVersion") = "1.0J"
BuildLanguage="Japanese"
BuildWin32=True
BuildMacMachO=True
DoCommand "BuildApp"

Here is a script that automates a build for Windows and Linux. You may need to use the appropriate SelectWindow commands to display the correct window for the commands.

PropertyValue("App.StageCode")="1"
DoCommand "BuildSettings"
PropertyValue("App.Windows.AppName")="TextEditor.exe"
BuildWin32=True
BuildLinux=True
BuildMacPEF=False
BuildMacMachO=False
BuildMacClassic=False
BuildRegion="United States"
BuildLanguage="English"
DoCommand "BuildApp"

# See Also

RBScript control.