From Real Software Documentation
Used in the IDE to script the development environment. To write an IDE Script, choose File ↠ IDE Scripts ↠ New IDE Script. An empty IDE Script editor appears. To open saved scripts, create a folder named "Scripts" in the same directory as the Real Studio application and save your scripts to that folder. When you do so, the scripts appear as submenu items in the IDE Scripts menu.
IDE Script is available only in Real Studio Enterprise and Web editions. In other versions of Real Studio, the IDE Scripts menu is not available.
Here is the list of IDE scripting commands.
|Beep||Plays the system beep.|
|BuildApp||String||Target as Integer||Builds the application for the passed platform. |
It takes one of the target constants listed below and returns the shell path to the built item (or empty string on error).
The method is synchronous.
|String||Target as Integer, |
Reveal as Boolean
|Builds the application for the passed platform. |
It takes one of the target constants listed below and returns the shell path to the built item (or empty string on error).
The method is synchronous.
|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. REALbasic 2007 Release 4 and above no longer build for Mac OS "Classic."|
|BuildMacCocoa||Boolean||Gets or sets whether to build for a Cocoa Mac OS X applications. Cocoa is being made available as a beta release in 2010r3.|
|BuildCurrentPlatform||Boolean||Gets or sets whether to build for the platform on which the IDE is running.|
|BuildMacMachOx86||Boolean||Gets or sets whether to build a Mach-O Macintosh application for the Intel platform.|
|BuildMacPEF||Boolean||Gets or sets whether to build a PEF Macintosh application. The PEF format is no longer supported.|
|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.|
|name as String, params as String= "", returnType as String= "", scope as Integer = "", implementsClause as String = ""||Changes the declaration. This changes the declaration but the syntax is not checked until you try to compile. The legal values for Scope are:|
0 - Public
|Clipboard||String||Gets or sets the contents of the copy/paste buffer, a.k.a. "clipboard."|
|ConstantValue||ConstantName as String||Gets or sets the default value of a project constant.|
|String||Contains the name of the application being built. This constant is useful only in Post build scripts.|
|String||The shell path to the item being built. This is not valid in pre-build steps and will be blank. The location will be wherever GetFolderItem would try to locate a file.
This variable literally does not exist unless you are doing a build. It is actually added by the IDE to the build scripts just before the script is run for each target. If you build for several targets (e.g., Mac OS X Intel, Windows) it is different for each target being built.
|Integer||An Integer that you can use to determine what kind of executable is being built. The values are the same as for BuildApp:|
kTargetWin32 = 3,
|Boolean||withPassword as String||Decrypts an item that was encrypted by EncryptItem using the passed password. Returns True if the item could be decrypted; otherwise it returns False.
Use SelectProjectItem to select the item this function operates on. With scripted encryption/decryption, it is important not to try to use this feature to try to brute-force decryption. An encrypted item will refuse to decrypt after three failed attempts (in a script or in the IDE itself) and further attempts will get slower and slower until the project is closed and reopened.
|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,
ByRef resultcode as Integer
|Executes the passed shell command. The result codes are the same as for the Shell class.|
The shell environment is set up with the following variables:
|Boolean||Password as String||Encrypts the currently selected item using the passed password. If the item is already encrypted, is a folder, or it can't be encrypted it returns False. It returns True in all other cases. It uses 2006r3 encryption. The item can be decrypted again using DecryptItem.|
|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.
|NewConsoleProject||Creates a new Console Project|
|NewGUIProject||Creates a New GUI project|
|NewWebProject||Creates a new Web app project|
|OpenFile||path as String||Attempts to open a Real Studio 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.|
|ProjectShellPath||String||Gets the shell path to the project file. If the project is not saved, it returns an empty string.|
|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".
|SaveDirtyItems as Boolean||Quits the IDE. If the passed SaveDirtyItems is True, any items that would normally require saving will be saved without prompting. If SaveDirtyItem is False, they will not be saved.|
|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.|
|Boolean||pathToItem as String||Selects the item specified by the path. Returns True if the item is successfully selected and returns False otherwise. Path is the path within the project view that is separated by periods. Items at the root of the project are specified by name alone. For example, in the default Desktop Application project, App, Window1, and MenuBar1 would be specified as:|
|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 TextField.SelText.)
|URL as String||Uses the appropriate web browser application (based on the user's Internet settings) to go to the HTTP URL specified.|
|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 tab-delimited String (Chrb(9)). In older versions, it was a space-delimited String. Since locations can have embedded spaces, the delimiter was changed to ChrB(9).
For example, with "App" passed to baseLocation, this function returns "App.Activate App.CancelClose App.Close" (and so on). If an empty string is passed as baseLocation, then this function returns the "topmost" set of project items in the frontmost project. Some items, like Modules and Folders, can contain other items. None of the items contained by the Module or Folder would be listed in this case. Calling sublocation with the name of the topmost container, the module or folder name, will give you the list of items contained by that folder or module.
|Text||String||Gets or sets the entire text of the current Code Editor.|
|TypeOfCurrentLocation||String||Returns a string that is the type of the current location.
If the location is the project item editor and there’s a selection then you will get the type of the selected item.
|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 REAL Studio IDE has its own IDE Script editor that you can use to automate many aspects of the development process. Choose File > IDE Scripts > New IDE Script to access the script 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. 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.
A saved script will be saved as a document on your hard disk. In addition, you can add a saved scrip to the IDE Scripts menu. 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.
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 is 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:
- Creating a new project, using NewProject, NewConsoleProject, NewGUIProject, or NewWebProject
- Changing the context (SelectWindow, Location)
- Changing project item properties (PropertyValue)
- Changing build settings (BuildLanguage, BuildLinux, 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).
Many commands that can be executed can be found by recording a script while you perform the desired action.
If you wish, you can choose to automate the build process. For example, you can specify the default language, the target platform, and set property values like build version of the target application. This is entirely optional; you can choose to build your application manually using the normal IDE controls.
You automate the build process using the Build Automation item that is added to every project. The item has blank placeholders for every target platform; you automate the build process by adding script items to the desired platform item.
Each platform group is populated with one item that represents the build. This item cannot be modified or deleted. Instead, you add script items to the platform group.
Each target contains one item. It represents the build project step for that platform. This step cannot be added, removed, or renamed. It marks the point in the list of build steps where the compilation of the application will occur. It also serves as the marker that determines what steps happen before the application is compiled and what steps occur after the application is compiled.
You can add separate build scripts for each target platform (Windows, Mac OS X, and Linux) and you can use the feature to specify what happens before the application is compiled and what happens after the application is compiled.
You add build steps using either the Project ↠ Add ↠ Build Automation submenu or the contextual menu. In the latter case, choose Add to Project ↠ Build Automation to display the submenu items. In both cases, you will see three items:
- Copy files
- New IDE script
- External IDE script
Adding an item does not nest the item inside one of the target platform groups. When it is external to all the Build Automation items, it is disabled from all targets. However, you can configure the item from this position. In all cases, you set the properties of the step to configure it.
Drag it into a target platform group to make it active:
Here are descriptions of all the script types.
Copy Files Step
The CopyFiles step copies a list of files to a selected destination. The destination for the copy is specified by the Destination property of the CopyFilesStep. The values are:
- App Parent Folder
- Resources Folder
- Framework Folder
- Bundle Parent Folder
Since REAL Studio is a cross-platform development tool, the destinations are specified in as cross-platform compatible way as possible. This table explains what happens on each platform.
|Destination||Mac OS X||Windows||Linux|
App Parent Folder
|Next to the executable in Bundle ↠ Contents ↠ Mac OS||Next to EXE||Next to EXE|
|Resources Folder||In Bundle ↠ Contents ↠ Resources||Directory containing EXE ↠ Resources||Directory containing EXE|
|Framework Folder||In Bundle ↠ Contents ↠ Frameworks||Directory containing EXE appname Libs||Next to EXE|
|Bundle Parent Folder||Directory containing the bundle||Directory containing EXE||Directory containing EXE.|
Use the Properties pane for a Copy Files step to specify the Destination from the pop-up menu.
The Subdirectory can also be entered as a string. The specified directory will be created and files copied into it. It will not create an entire relative directory path at present.
Use the Files property to add files. It offers a dialog in which you can add the files.
New IDE Script
A new IDE script is created inline. It is not stored externally to your project like other (external) IDE scripts. If you send a project that contains an internal IDE script, the script will be included as part of the project. You add the internal script as the Script item in the Properties pane. Click the Script property to open a dialog in which you can enter the script.
There are two new variables available for IDE build scripts, CurrentBuildLocation and CurrentBuildTarget. CurrentBuildLocation is the shell path to the item being built. It is not valid in pre-build steps and will be blank. This location will be wherever GetFolderItem would try to locate the file. CurrentBuildTarget is an Integer value that you can use to determine what kind of executable is being built. It uses the same constants as BuildApp.
External IDE Script
An external IDE script is stored externally to your project. It is just a reference to an external file. You specify the script file using the File property of the External Script's Properties pane. Click in the File area to open a browser area.
Since an external script is a reference, they are not included as part of the project. If you send such a project to another person, you will need to include the external script file or files.
Scripting Encoding and Decoding Items
Several new commands have been added to allow you to encrypt and decrypt items via a script. You use SelectProjectItem to select the item to be encrypted/decrypted, EncryptItem to do the encryption, and DecryptItem to decrypt the selected item, assuming it is already encrypted. Each returns True if the operation was successful.
You first select an item to be encrypted by passing SelectProjectItem the path. If SelectProjectItem is successful, it returns True. You can then try to encrypt it by passing EncryptItem a password. For example:
Decrypting an item works the same way:
The path that is passed to SelectProjectItem uses the dot notation, e.g, folder1.folder2.module1.
The following script issues the traditional greeting via a MsgBox:
This script sets the ShortVersion to "1.0J", sets the build language to Japanese, and then builds a Mac version of the application:
BuildLanguage = "Japanese"
BuildWin32 = False
BuildLinux = False
BuildMacMachOX86 = True
PropertyValue("App.MacOSXAppName") = "Test Application"
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.MinorVersion") = "1.5"
PropertyValue("App.WindowsAppName") = "TextEditor.exe"
PropertyValue("App.LinuxAppName") = "Text_Editor"
BuildWin32 = True
BuildLinux = True
BuildMacMachOX86 = True
BuildRegion = "United States"
BuildLanguage = "English"
Use the following skeleton to encrypt or decrypt a list of items in your project.
This example assumes you have in your project a folder named "EncyptedItems" and in it two classes named "Class1" and "Class2" that you want to have encrypted or decrypted.
Const password = "xyz" // enter the password here
// List the items for de-/encryption here:
Dim items() As String = Array ( _
Dim s, failures() As String
For Each s In items
If Not SelectProjectItem (s) Then
Print "Failed to select " + s + ". Stopping."
If decrypt Then
If Not DecryptItem (password) Then
If Not EncryptItem (password) Then
If failures.Ubound >= 0 Then
If decrypt Then
Print "Failed to decrypt "+Join(failures,", ")
Print "Failed to encrypt "+Join(failures,", ")