Beginning REALbasic - From Novice To Professional (2006)

All three comment statements are functionally equivalent. There is no advantage to using one type of comment over another. You can embed comments within your REALbasic applications using any of these options, as the following demonstrates.

'Define a variable name blnAnswer with a data type of Boolean Dim blnAnswer As Boolean

//Define a variable name blnAnswer with a data type of Boolean Dim blnAnswer As Boolean

REM Define a variable name blnAnswer with a data ttype of Boolean

Dim blnAnswer As Boolean

REALbasic enables you to add comments to the end of statements, as the following shows.

■Note If you have a number of consecutive code statements that you want to comment, you can do so by selecting these statements, and then clicking the Comment Command button located on the Code Editor toolbar or by clicking Edit Comment. When you do so, REALbasic responds by adding a single-quote comment character to the beginning of each statement and changing the Comment Command button into the Uncomment Command button (Edit Uncomment).

Notes

Another option of embedding comments directly into your applications is to add notes. A note is an item you can add in the browser window located in the Code Editor. Like regular comments, notes are not compiled and have no effect on application performance. The following procedure outlines the steps involved in adding a note to applications.

1.Open the Code Editor for the resource for which you want to add the note.

2.Click the Add Note button located on the Code Editor toolbar or click Project Add Note.

3.Enter a name for the Note in the Note Name field.

4.Enter your comments into the data entry area, as Figure 5-1 shows.

Figure 5-1. Embedding a note in a REALbasic application, as shown on Macintosh

Property Comments

REALbasic also provides you with the capability to document any properties you add to windows, classes, and modules. Properties are added by clicking the Add Property button or by clicking Project Add Property. As Figure 5-2 shows, you can add comments beneath any property by entering text in the data entry area beneath the property declaration data.

Figure 5-2. Embedding comments into Property declarations, as shown on Linux.

Information on classes and modules is provided in Chapter 8.

Storing and Retrieving Data

Like other programming languages, REALbasic provides the capability to store and retrieve data in memory while applications are running. Data is the information applications collect, process, and store when running. REALbasic provides you with two primary means of storing and retrieving data that changes during program execution: variables and arrays.

A variable provides your application with the capability to store data that may change while the application executes. Variables are logical pointers to locations in memory where data is stored. An array is an indexed list of related data. By providing the capability to store related data in collections, REALbasic equips you with a tool for storing and processing large amounts of data with relatively few programming statements, which makes for more efficient program code.

REALbasic provides other options for working with data, including constants, dictionaries, and classes. Dictionaries and constants are covered in the sections “Working with Dictionaries” and “Constants.” To learn about classes, see Chapter 8.

Working with Variables

Variables are used to store and process individual pieces of data, such as values in an equation or the number of turns left in a game. Unlike constants, variables are meant to store data that changes during application execution. REALbasic variables are capable of working with many different types of data, such as text strings and different types of numbers. Table 5-1 provides a listing of the different data types that REALbasic supports.

Table 5-1. REALbasic Data Types

SPECIFYING THE CORRECT DATA TYPE

By specifying the correct data type for each piece of data processed by your application, you optimize your application to run as efficiently as possible by conserving the amount of memory required to store data. A trade off exists, however, between your development time and the savings in time your applications may, ultimately, realize if you tweak memory usage to perfection. In more cases, you won’t see any tangible improvement in performance no matter how carefully you specify variable data types. As such, you’ll probably be best served in 99 percent of all cases by using the following commonly used data types: Boolean, Color, Double, Integer, Single, String, and Variant.

As shown in Table 5-1, REALbasic provides support for a wide variety of data types, each of which is designed to store a different type of data. When you instruct REALbasic as to what data type to associate with a particular variable, you tell it what types of actions are permissible when working with the variable. For example, numeric data types, such as an integers, can be added together, but they cannot exceed a maximum value of 2,147,483,647. On the other hand, a special data type, such as a Boolean value, can only be set equal to True or False.

Working with Properties

Variables directly related to REALbasic objects, such as a window, PushButton, or menu, are referred to as properties of objects. Properties are accessed by name and have specific data types. For example, the Caption property of a PushButton control has a data type of string.

Assigning Values to Properties

Many properties are available for modification at design time. However, you can also modify most properties programmatically during program execution. The following outlines the syntax for property assignment.

ObjectName.PropertyName = Value

As you can see, to assign a value to a property, you must identify the name of the owning object, the name of the property, and the value you want to assign to the property. Take note of the dot that separates the ObjectName and PropertyName in the previous example. This is an example of dot notation or dot syntax and is the standard means by which you refer to object attributes like properties.

The following shows an example of how to assign a value to a property.

PushButton1.Caption = "Cancel"

■Note Similar dot notation was used back in Chapter 4 to enable access to menu items. Likewise, when you supply the program code required to build the RBCalculator application, which you read about in the section “Supplying Application Code,” you’ll see additional examples of how to programmatically control access to interface elements by modifying control properties.

In this example, the Caption property associated with an instance of a PushButton control named the PushButton1 is assigned a value of Cancel. Note, this example assumes the code for this statement was placed within the method belonging to the window where the PushButton1 control was added or within one of the methods belonging to a control on that window. If, on the other hand, the PushButton1 control resides on another window, you must specify the full path to the control using the following syntax to refer to it.

WindowName.ObjectName.PropertyName = Value

■Note Up to this point in the book, you have been keying in code statements associated with either a window or one of its controls. The collection of code statements associated with either of these types of resources is referred to as a method within REALbasic programming. You learn more about methods later in Chapter 8.

For example, if the PushButton1 control you wanted to modify resided on a window named Window2, you would need to modify this example as the following shows.

Window2.Pushbutton1.Caption = "Cancel"

ME AND SELF

REALbasic provides a pair of useful programming shortcuts you may want to use to streamline your program statements. Me is a keyword that refers to the control in which program code is placed. By referring to Me in place of a control’s name, you can reduce the amount of keystrokes required to complete your code statements. For example, you could rewrite

PushButton1.Caption = "Cancel"

as

Me.Caption = "Cancel"

This example assumes the code for this statement is located within the method associated with the PushButton1 control. Another advantage of using the Me keyword in place of a specific control’s name is this: because the Me keyword is generic, you can reuse it by copying-and-pasting it into the method of another PushButton control without then having to modify the ObjectName part of the statement.

Self is a keyword that refers to a control’s parent object. For example, the parent object of a PushButton control would be the window on which it was placed. Thus, instead of programmatically referring to a window’s Title property from within one of its controls as

Window1.Title = "My test Application"

You could, instead, generically reference the property using the Self pronoun as the following shows.

Self.Title = "My test Application"

Retrieving Property Values

In addition to assigning a value to a property, you can also retrieve it using the following syntax.

Result = ObjectName.PropertyName

Here, the value assigned to the PropertyName is assigned to a variable named Result. For example, the following statement retrieves the value assigned to the Caption Property of the PushButton1 control

x = PushButton1.Caption

If the Property resides on a different window, you would have to modify this statement, as the following shows.

x = Window2.PushButton1.Caption

Creating and Working with Variables

When you need to store and retrieve individual pieces of data that are not directly associated with an object, such as a control, you will want to store them in regular variables. REALbasic enables you to create variable names of any length. Variables names are not case-sensitive, so as far as REALbasic is concerned, TEMP, tEMP, and TeMp are all the same. REALbasic does impose a few rules on the creation of variable names, as shown in the following list:

•Variable names must begin with a letter.

•Variable names can only contain uppercase and lowercase alphabetic characters and numbers.

•Variable names cannot contain blank spaces.

•Reserved words cannot be used as variable names.

Defining Variables and Assigning Data

Two steps are involved in creating a variable. For starters, you must declare the variable using the Dim statement. In declaring a variable, you give it a name and specify the type of data it will store. The following shows the syntax of the Dim statement.

Dim VariableName As DataType

For example, the following statement declares a variable named strUserName that will hold string data.

Dim strUserName As String

Once you declare a variable, you can assign data to it, as the following shows.

strUserName = "Alexander Ford"

■Tip Always be sure to assign a value to your variables. If you forget, REALbasic will substitute a default value, which can create unpredictable results in your applications. For example, if you fail to assign a value to a variable with a numeric data type, REALbasic assigns a default value of 0. Similarly, if you fail to assign a value to a variable that stores string data, REALbasic automatically assigns an empty string ("") as the variable’s default value.

REALbasic is flexible in the manner in which it enables you to declare variables. For example, it lets you declare more than one variable of the same data type at a time using a single Dim statement, as the following shows.

Dim strFirstName, strLastname As String

REALbasic lets you mix and match data types in declaration statements, as you see here.

Dim strUserName As String, strUserAge as Integer

REALbasic also enables you to assign a value to a variable at the same time you declare it, as the following shows.

Dim strPlayAgain As Boolean = False

■Note One thing REALbasic does not do, and this may surprise Visual Basic programmers, is let you implicitly create variables simply by referencing them, without first declaring them.

CREATING MORE USEFUL VARIABLE NAMES

To help make your REALbasic code statements easier to understand, use a variable-naming scheme. For example, going forward, the examples in this book use variables whose names begin with a three-character prefix that identifies their data type. In addition, the names assigned to all variables attempt to describe their use or contents. Examples of common prefix characters include

•Boolean - bln

•Color - clr

•Double - dbl

•Integer - int

•Single - sng

•String - str

•Variant - var

Determining Variable Scope

A key concept you should be aware of when working with variables is scope. A variable’s scope determines which parts of your REALbasic application can access a variable. Variables declared using the Dim statement are local in scope, which means the variables can only be accessed within the method where they were defined.

For example, if you declare a variable named strUserName in a method belonging to a PushButton control, that variable can only be accessible by other programming statements associated with that method. You can declare a variable anywhere you want within a method, just as long as you declare it before other code statements that reference it.

You can further refine variable scope with methods by declaring variables within If…Then statements and looping statements. These types of statements, and any code stored within them, represent a block of code. Any variable declared within a code block is local only to that code block. For example, the following example shows a declaration statement located inside an If…Then code block. Any other code statements in the method where this If…Then code block resides will be unable to access the variable. Information on how to work with If…Then and looping statements is available in Chapters 6 and 7.

If intUserAge > 21 Then

Dim blnAccessFiles As Boolean blnAccessFiles = True

End If

If, on the other hand, you need to set up a variable with a broader scope, you can add a module to your application and define the variable within the module. This gives the variable a global scope, meaning it can be accessed from any part of the application. Modules are discussed in Chapter 8.

■Tip In addition to being considered a good programming practice, limiting the scope of variables help to prevent the code in one part of your application from accidentally changing a similarly named variable’s value in another part of your application.

Converting Between Data Types

As you work with variables in your REALbasic applications, at times, you might need to convert the data type of values stored in properties and variables. For example, any time you use an EditField control to collect numeric data from users, you need to convert that data from string to a numeric format because REALbasic treats anything entered into an EditField control as a string.

Built-In Conversion Functions

To help make things easier for you, REALbasic provides a number of built-in functions you can use to convert data from one data type to another. These functions include the following:

•CDbl. Converts a string value into a numeric value with a Double data type. This function is typically used to convert data supplied by the user.

•CStr. Converts any data type into a string value.

•Str. Converts a numeric value into a string value.

•Val. Converts a string value into a numeric value with a Double data type. This function is typically used to convert data generated by code within your application.

The following statement demonstrates how to work with the CDbl conversion function.

Dim dblUserAge As Double dblUserAge = CDbl(EditField1.Text)

In this example, a variable named dblUserAge capable of storing double data is declared. Then, a value is retrieved from an EditField control and is converted to a double and assigned to dblUserAge. You can just as easily convert a integer to a string data type, as the following shows.

Dim intUserAge As Integer = 30

EditField1.text = CStr(strUserAge)

In this example, the integer value stored in the intUserAge variable is converted to a data type of string, and then displayed in an EditField control.

String Manipulation Functions

Another common programming technique you need to know when developing REALbasic applications is how to manipulate and extract the contents of strings. In fact, string manipulation is such a commonly performed task that REALbasic provides a number of built-in string handling functions to assist you, as the following list shows.:

•InStr. Searches for a string within another string.

•Len. Returns a string’s length.

•Lowercase. Converts a string to lowercase characters.

•Ltrim. Removes leading spaces from the left-hand side of a string.

•Mid. Extracts a portion of a string.

•Replace. Replaces one string with another string.

•Rtrim. Removes trailing spaces from the right-hand side of a string.

•Trim. Removes both leading and trailing spaces from a string.

•Uppercase. Converts a string to uppercase characters.