IDE Script

From Xojo Documentation
Revision as of 23:34, 11 February 2012 by PLefebvre (Talk | contribs)

Jump to: navigation, search

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

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

Introduced 2009r4

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.

Introduced 2008r5
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.

The Project Editor with the Build Automation item.


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.


The empty build steps in the default desktop application.

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.


A new Copy Files step.


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:


An enabled Copy Files step.


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.

The Files dialog box.

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.

New IDE Script dialog box.


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:

If SelectProjectItem ("Class1") then
If EncryptItem("Swordfish") then
Beep
End if
End If


Decrypting an item works the same way:

If SelectProjectitem("Class1") then
If DecryptItem("Swordfish") then
Beep
End if
End if


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:

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 = False
BuildLinux = False
BuildMacMachOX86 = True
PropertyValue("App.MacOSXAppName") = "Test Application"

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"
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"

DoCommand "BuildApp"


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 decrypt = True // change this to encrypt or decrypt
Const password = "xyz" // enter the password here

// List the items for de-/encryption here:
Dim items() As String = Array ( _
"EncyptedItems.Class1", _
"EncyptedItems.Class2" )

Dim s, failures() As String
For Each s In items
If Not SelectProjectItem (s) Then
Print "Failed to select " + s + ". Stopping."
Exit
Else
If decrypt Then
If Not DecryptItem (password) Then
failures.Append s
End If
Else
If Not EncryptItem (password) Then
failures.Append s
End If
End If
End If
Next

If failures.Ubound >= 0 Then
If decrypt Then
Print "Failed to decrypt "+Join(failures,", ")
Else
Print "Failed to encrypt "+Join(failures,", ")
End If
End If

See Also

RBScript control.

Personal tools
Namespaces

Variants
Actions
Main
Documentation
Community
Toolbox
Help