RBScript Class

Used to execute REALbasic code within a running (compiled) application.

Events

CompilerError

Input

Print

RuntimeError


Properties

Context

EncodingFont

Source

State


Methods

PartialRun

Precompile

Reset

Run


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.

NameTypeDescription
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:

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"

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:

Dim Years, Days as Integer
Years = Val(Input(""))
Days = Years * 365

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:

Dim Years, Days as Integer
Years = Val(Input(""))
Days = Years * 365
Print Str(days)

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:

Sub Print(msg as String)
 StaticText1.text = msg

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:

Integer

Single

Double

Boolean

String

Color

Object

Variant

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.

Class NewClass
  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:

Module Foo
  Dim bar As Integer
  Sub Baz ()
  bar = 42
 End Sub
End Module

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.

Class MyNewSubClass
 Inherits NewClass
 //continue coding here....
End Class

Events

Classes can declare new events using a New Event declaration.

Class myClass
  New Event myEvent (myParameter as DataType) as DataType
End Class

Methods can handle such events using the Handles Event declaration. For example:

Class myClass
  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:

Interface MovableItem
  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:

Class Box
 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

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

FunctionComment
Abs( Double) As Double
Acos( Double) As Double
Asc( String) As Integer
AscB( String) As Integer
Asin( Double) As Double
Atan( Double) As Double
Atan2( Double, Double) As Double
BitwiseAnd( Integer, Integer) As Integer
BitwiseOr( Integer, Integer) As Integer
BitwiseXor( Integer, Integer) As Integer
ByRef keyword
ByVal keyword
CDbl( String) As Double Identical to Val().
Ceil( Double) As Double
Chr( Double) As String
ChrB( Double) As String
CMY
Color
Const name = value
Cos( Double) As Double
CountFields( String, String) As Integer
CStr( Double) as String
Dim Allows you to declare multiple variables with different types rather than only multiple variables of the same type. Empty arrays can be created by specifying -1 elements.
Do...Loop
Exit
Exp( Double) As Double
False
Floor( Double) As Double
For...Next Allows floating point loop counters and step values.
Format( Double, String) As String
Function Functions can be called before they are defined.
Goto keyword
Hex( Integer) As String
HSV
If...Then...Else
InStr( Integer, String, String) As Integer
InStrB( Integer, String, String) As Integer
IsA operator Can be used with Object; it will return True for any non-null object.
Left( String, Integer) As String
LeftB( String, Integer) As String
Len( String) As Integer
LenB( String) As Integer
Log( Double) As Double
Lowercase( String) As String
LTrim( String) As String
Max( Double, Double) As Double
Me
Microseconds As Double
Mid( String, Integer, Integer) As String
MidB( String, Integer, Integer) As String
Min( Double, Double) As Double
Nil
NthField( String, String, Integer) As String
Oct( Integer) As String
Pow( Double, Double) As Double
Redim
Rem
Replace( String, String, String) As String
ReplaceB( String, String, String) As String
ReplaceAll( String, String, String) As String
ReplaceAllB( String, String, String) As String
RGB
Right( String, Integer) As String
RightB( String, Integer) As String
Rnd As Double
Round( Double) As Double
RTrim( String) As String
Select Case
Self
Sin( Double) As Double
Sqrt( Double) As Double
Str( Double) As String
StrComp( String, String, Integer) As Integer
Sub
Tan( Double) As Double
Ticks as Integer
Titlecase( String) As String
Trim( String) As String
True
Ubound(array) As Integer Supports second parameter for multi-dimensional arrays.
Uppercase( String) As String
Val( String) As Double Scientific format not recognized.
While...Wend

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