RBScript Class
Used to execute REALbasic code within a running (compiled) application.
More information available in parent classes: Object
IDE Scripting
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. If you have saved scripts, they are added to the IDE Scripts submenu. You will be given a chance to save your script when you close the IDE Script editor.
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 detailed in the table that follows. 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, 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).
Here is the list of IDE scripting commands.
Name | Type | 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 | Parameter is 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 | Parameters are cmd as String and timeout as Integer. The default value for timeout is 3000. Executes a 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. |
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 | Parameter is 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 | Parameter is 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 | Parameter is 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 | Parameter is 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 | Parameter is 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 | Parameters are text as String and Interrupt as Boolean = False. Speaks the passed text via the system's speech synthesis engine. 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 | Parameter is 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 | Parameter is 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. |
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:
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.
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"
Notes
The RBScript language is an implementation of the REALbasic language that allows end users to write and execute REALbasic code within a compiled application. Scripts are compiled into machine language, rather then being interpreted.
Since RBScript is a class, you use it by creating an instance of this class either via code or by adding an RBScript control to a window. The easiest way to use RBScript is to assign the code to the Source property of the RBScript object and call the Run method.
To provide information to an RBScript while it's running, use the Input function. This function calls the Input event of the RBScript object where you can return the information you wish returned by the Input function in your RBScript code. In the following example, the results of the Input function are assigned to a variable:
The Input function takes a String that can be used to provide a prompt in case you are going to provide a dialog box in which the user enters the information. Since the Input function returns a String and we want to store the value as an integer, the Val function is used to convert the string to an integer. In this case, if the number of years is going to be entered into an EditField called Editfield1, then the Input event of the RBScript object would look like this:
When the Run method of the RBScript object is called, the code will be compiled and then executed. Since the Input function is called, the Input event of the RBScript object is executed and the contents of the Text property of the EditField is returned and assigned to the Years variable. Then the Days value is calculated.
Getting Information From RBScript
You obtain data from the RBScript using the Print method. This method takes a String and passes it to the Print event of the RBScript object. Here is the example modified to use the Print function:
You access the value passed to the Print method through the Print event. For example, if you want to assign the value to the Text property of a StaticText object, the code for the Print event of the RBScript object would look like this:
Handling Errors in Your Code
If an error occurs while RBScript is compiling your code, the CompilerError event of the RBScript object will be called and will be passed appropriate error information so you can then decide how to handle the error. If the error occurs while the code is running, the RuntimeError event of the RBScript object is called and is passed appropriate error information. You can then decide how to respond to the error.
Variables and Constants
All numeric and alphanumeric operators are supported:
+, -, *, /, \, Mod, <, =, >, <=, >=, <>.
Logical operators: And, Not, Or.
All forms of comments are supported: ', //, and REM.
Data Types
RBScript supports the following data types:
Arrays can use any of these types.
Control Structures
All the control structures specified in this Language Reference are supported. This includes:
Function...
Sub...
For... Next
Do... Loop
If... Then... End If
Select Case... End Select
While...Wend
Return statement
Classes
You can create a class using the Class...End Class structure. A new class can have properties, methods, and events.
Dim i as Integer //Property definitions..
Dim c as Color
Sub myMethod (x as Integer, y as Integer)
//Method definition goes here
End Sub
//Class definition
End Class
A class can be subclassed from another class using the "Inherits" declaration.
Modules
You can create modules using the Module structure. For example:
Modules are similar to REALbasic modules. The differences are that properties are always protected and constants are not allowed. You can get the effect of a public property or constant by simply putting the Dim or Const statement outside of the module.
TypeCasting
Typecasting is supported. Use the desired type's name as a function whose only argument is the object reference you want to cast. If it fails, it will trigger an IllegalCastException error.
"Super" keyword
The new "Super" keyword lets you call overridden methods without having to specify which class the method came from. This works for constructors as well. You can call overridden superclass methods using REALbasic's classname.methodname() syntax.
Inheritance
Class inheritance is implemented with the "Inherits" declaration.
Inherits NewClass
//continue coding here....
End Class
Events
Classes can declare new events using a New Event declaration.
Methods can handle such events using the Handles Event declaration. For example:
New Event myEvent (myParameter as DataType) as DataType
End Class
Class mySubClass
Inherits myClass
Function myEvent (myParameter as DataType) Handles Event
//continue with function here
End Function
End Class
Interfaces
RBScript now supports interfaces, declared by the Interface...End Interface structure. Interface methods are declared with a Sub or Function line just as they would be declared inside a class, but they have no contents and need no End Sub or End Function line:
Sub Move( x As Integer, y As Integer)
Function LocationX() As Integer
Function LocationY() As Integer
End Interface
Function declarations with no parameters must have empty parentheses, as shown above.
A class may declare that it implements an interface with the Implements keyword:
Implements MovableItem
End Class
Classes can implement any number of interfaces, but they must provide all of the methods listed in the interface. Interfaces can be used in all the situations as in REALbasic.
Input and Output
Function | Comments |
Input(Prompt as String) | Retrieves input from the user. This function triggers the Input event. |
Print(String) | Sends output to the implied output device. This function triggers the Print event. |
Functions
Standard library functions are supported as follows. These functions work as specified in this Language Reference unless comments indicate otherwise. String functions can be called using the syntax of methods, just as in REALbasic.
Compiler error numbers returned in errorNumber are shown below:
{table} {headers: Error Number, Description} {row}1 {col} Syntax does not make sense. {row}2 {col} Type mismatch. {row}3 {col} Select Case does not support that type of expression. {row}√ {col} The compiler is not implemented (obsolete). {row}5 {col} The parser's internal stack has overflowed. {row}6 {col} Too many parameters for this function. {row}7 {col} Not enough parameters for this function call. {row}8 {col} Wrong number of parameters for this function call. {row}9 {col} Parameters are incompatible with this function. {row}10 {col} Assignment of an incompatible data type. {row}11 {col} Undefined identifier. {row}12 {col} Undefined operator. {row}13 {col} Logic operations require Boolean operands. {row}14 {col} Array bounds must be integers. {row}15 {col} Can't call a non-function. {row}16 {col} Can't get an element from something that isn't an array. {row}17 {col} Not enough subscripts for this array's dimensions. {row}18 {col} Too many subscripts for this array's dimensions. {row}19 {col} Can't assign an entire array. {row}20 {col} Can't use an entire array in an expression. {row}21 {col} Can't pass an expression as a ByRef parameter. {row}22 {col} Duplicate identifier. {row}23 {col} The backend code generator failed. {row}24 {col} Ambiguous call to overloaded method. {row}25 {col} Multiple inheritance is not allowed. {row}26 {col} Cannot create an instance of an interface. {row}27 {col} Cannot implement a class as though it were an interface. {row}28 {col} Cannot inherit from something that is not a class. {row}29 {col} This class does not fully implement the specified interface. {row}30 {col} Event handlers cannot live outside of a class. {row}31 {col} It is not legal to ignore the result of a function call. {row}32 {col}Can't use "Self" keyword outside of a class. {row}33 {col}Can't use "Me" keyword outside of a class. {row}34 {col}Can't return a value from a Sub. {row}35 {col}An exception object required here. {row}36-39 {col}Obsolete. {row}40 {col}Destructors can't have parameters. {row}41 {col}Can't use "Super" keyword outside of a class. {row}42 {col}Can't use "Super" keyword in a class that has no parent