IDE Script

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.

Contents 1 Commands 2 Notes 2.1 Recording 2.2 IDE Scripting Commands 2.3 DoCommand 2.4 Build Automation 2.5 Copy Files Step 2.6 New IDE Script 2.7 External IDE Script 2.8 Scripting Encoding and Decoding Items 3 Examples 4 See Also

Commands

Here is the list of IDE scripting commands.

Name	Type	Parameters	Description
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. Here are the constants for Target: kTargetWin32 = 3, kTargetLinuxGTK = 4, kTargetCarbonMachOi386 = 6, kTargetCocoai386 = 7, After it builds the application, it obeys the current setting of the "Show built applications on the Desktop" option (preference on Macintosh).
BuildApp Introduced 2008r4	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. Here are the constants for Target: kTargetWin32 = 3, kTargetLinuxGTK = 4, kTargetCarbonMachOi386 = 6, kTargetCocoai386 = 7, If the parameter Reveal is True, then it will reveal the application after a successful build. This is equivalent to the "Show Built Applications on the Desktop" option in Options (Preferences on Macintosh).
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.
ChangeDeclaration Introduced 2011r2		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 1 - Protected 2 - Private
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.
CurrentBuildAppName Introduced 2009r1	String		Contains the name of the application being built. This constant is useful only in Post build scripts.
CurrentBuildLocation Introduced 2008r5	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.
CurrentBuildTarget Introduced 2008r5	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, kTargetLinuxGTK = 4, kTargetCarbonMachOi386 = 6, 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.
DecryptItem Introduced 2009r2	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: 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.
EncryptItem Introduced 2009r2	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".
QuitIDE Introduced 2009r2		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.
SelectProjectItem Introduced 2009r2	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: SelectProjectItem("App") and so forth. If you have a folder containing the item foo, then the path would be: SelectProjectItem("Folder1.foo") Doubly nested project item would be: SelectProjectItem("Folder1.Folder2.foo")
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.)
ShowURL Introduced 2008r2		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.

Notes

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.

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

DoCommand

Many commands that can be executed can be found by recording a script while you perform the desired action.

Build Automation

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 project can have its own pre and post-build IDE script. With these scripts you can add “hooks” for third-party tools to run IDE scripts. The scripts are placed in the Build Automation item in the Project Editor window. This item is included in all Desktop Application projects, regardless of whether you want to automate the build process.

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.

Examples

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:

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.

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.

See Also

RBScript control.