From Real Software Documentation

Contents 1 Real Studio Web Tutorial 1.1 Welcome to the Real Studio Web Tutorial! 1.1.1 Presentation Conventions 1.2 Getting Started 1.3 Creating the Interface 1.3.1 Your application’s interface is now complete! 1.4 Giving Objects Meaningful Names and Labels 1.5 Making the URL Manager Do Something 1.6 If the Application Doesn’t Run 1.7 The Add Button 1.8 The Delete Button 1.9 The ListBox 1.10 Testing the Application 1.11 Using Autocomplete 1.12 If the Application Doesn’t Run 1.13 Building A Standalone Application 1.14 What’s Next

Real Studio Web Tutorial

Welcome to the Real Studio Web Tutorial!

This Tutorial is for people who are new to programming and new to Real Studio Web Edition. It is an introduction to the Real Studio Web development environment and will lead you through the development of a real web application.

The Web Edition is a feature of the Web or Enterprise editions of Real Studio. Users without appropriate licenses can try out the Web Edition in Demo mode. The Demo mode does not save your projects and runs them for only a brief period. If you do not have an Enterprise or Web license, then you can learn about the Desktop Edition in its own QuickStart and Tutorial.

It should take you about an hour to complete this tutorial.

Note: If you have experience with other versions of the BASIC language or other programming languages, you’ll want to check out the User’s Guide. In the Language Reference, check out the “Web” theme for the commands that are specific to the Web Edition.

Presentation Conventions

The Web Tutorial uses screen snapshots taken from the Windows, Macintosh, and Linux versions of Real Studio. The interface design and feature set are identical on all platforms, so the differences between platforms are cosmetic and have to do with the differences between the Windows7/Vista Aero interface, the Mac OS X Leopard interface, and the Linux Ubuntu distribution. Of course, the Web application that you will build is intrinsically cross-platform.

• Italic type is used to emphasize the first time a new term is used and to highlight important concepts. In addition, titles of books, such as Real Studio User’s Guide, are italicized.

• When you are instructed to choose an item from one of Real Studio’s menus, you will see something like “choose File ↠ New Project”. This is equivalent to “choose New Project from the File menu.”

• The items within the parentheses are keyboard shortcuts and consist of a sequence of keys that should be pressed in the order they are listed. On Windows and Linux, the Ctrl key is the modifier; on Macintosh, the ⌘ (Command) key is the modifier. For example, when you see the shortcut “Ctrl+O” or “⌘-O”, it means to hold down the Control key on a Windows or Linux computer and then press the “O” key or hold down the ⌘ key on Macintosh and the press the “O” key. You release the modifier key only after you press the shortcut key.

• Something that you are supposed to type is quoted. Some steps ask you to enter lines of code into the Real Studio Code Editor. They appear in a shaded box:

When you enter code, please observe these guidelines:

• Type each printed line on a separate line in the Code Editor. Don’t try to fit two or more printed lines into the same line or split a long line into two or more lines.
  
• Don’t add extra spaces where no spaces are indicated in the printed code.

Whenever you run your application, Real Studio first checks your code for spelling and syntax errors. If this checking turns up an error, Real Studio will direct your attention to the line of code that is causing problems. Check the line against the printed line. The Web Tutorial includes troubleshooting sections that help you handle syntax errors.

Getting Started

You’ll build an application that manages URLs and email addresses. A URL (which stands for Uniform Resource Locator) is the address of a web page that you type into the Address area in your web browser. This application will launch your default web browser application and display the web page that you entered. The following illustration shows a URL in an internet browser’s Address area:

If you enter an email address instead of a URL, the application will launch your email application, create a new blank email, and enter the address into the “To” box. The next illustration shows how to enter an email address into a browser’s Address area.

When you are finished, the application will look like this.

In the following illustration, the labels indicate the types of controls that were used in creating the application. The application uses three types Real Studio controls to do most of the work for you:

• A WebListBox is the type of control that holds scrollable lists. It can hold both single and multiple-column lists and scroll horizontally and vertically.
  
• A WebTextField is the type of control that holds a single line of text.
  
• A WebButton is a standard pushbutton. It is most often used to initiate an action (as it is here).
  

You use the TextField to enter the URL or email address you want and then click the Connect button. To save it in the list, you click the Add button. To select a URL in the ListBox, highlight it in the list and then click Connect. If you don’t need the URL any more, highlight it in the list and then click the Delete button.

Creating the Interface

If you have not already done so, double-click the Real Studio application icon. In a few moments, the New Project dialog box appears. The first thing you need to do is choose what type of project to create. Your choices are:

• Desktop Application: An application with a graphical user interface that runs on the Macintosh, Windows, and Linux operating systems.
• Console Application: An application with no graphical user interface that runs on one or more of the desktop operating systems.
• Web Application: An application that is deployed on the web and served to end users by a web server such as Apache.

Choose File ↠ New Project. The New Project Dialog box appears. In this dialog box you choose among building an application for a desktop platform (Windows, Macintosh, or Linux), a Web application, or a console application. Select Web and click Choose. The Real Studio integrated development environment (IDE) for Web development appears.

The IDE uses a tabbed interface to display multiple editors in the same window. Notice that two tabs are open. The Web Edition displays the Web Layout Editor as the top panel in the IDE. You switch among the editors by clicking on the Tabs in the Tabs bar. The first tab for the Project Editor is already open. We will get to the Project Editor later (each type of project has its own Project Editor.) Your first task is to build the interface with the Web Layout Editor.

The initial view shows a Web Layout Editor for the default WebPage. A WebPage is analogous to a document window in a Desktop application.

The editor for WebPage1 is shown in below.

The Web Layout Editor is divided into three panes. The pane on the right is the Properties pane and it shows the properties of the selected item in the WebPage Editing area. In this illustration, the WebPage is selected, so the Properties pane shows the properties of the web page.

The center pane is the WebPage Editing area. It is where you design the page. In this illustration, the page is blank because you haven’t added any interface items yet. It shows only a default page.

The pane on the left is the list of controls that you can add to a WebPage. The Controls Pane shows the complete list of built-in Web interface elements that can be added to a WebPage. It contains items for the WebListBox, WebTextField, WebButton, and many more. You add a control to a WebPage by dragging it from the Controls Pane to a location on the WebPage.

In the first exercise, you’ll add a ListBox seen in the final version of the application.

In the Controls pane, hold down the mouse button on the ListBox item and drag it to the top-left corner of the page in the Editing area. As you drag toward the corner, alignment guides will appear, as shown below. You may need to drop the ListBox near the correct area and then drag it again to see the alignment guides. Alignment guides help you position the ListBox and align other controls. Release the mouse button. A square ListBox appears in the WebPage Editor. Grab the resizing handle in the bottom-right corner of the ListBox and drag it diagonally to enlarge the ListBox. When the alignment guide appears on the right, release the mouse button, as shown below. Enlarging the ListBox. Center it in the upper area of the window, shown here. Next, drag a Button control from the Controls pane to the lower-left corner of the window. As you drag toward the left edge of the ListBox, a vertical alignment guide appears. Use the vertical alignment guide to position the Button, as shown below. Aligning the Add Button. With the Button selected, press Ctrl+D (Windows and Linux) or ⌘-D (Macintosh) or choose Edit ↠ Duplicate to make a copy of the Button. Move it to the right of the previous button and align it with the right edge of the ListBox and the baseline of the other Button’s text. When you reach the approximate position, both vertical and horizontal alignment guides appear. Align the baselines of the two Buttons’ captions, as shown below. Aligning the Add and Connect Buttons. With this Button selected, press Ctrl+D (Windows and Linux) or ⌘-D (Macintosh) or choose Edit ↠ Duplicate to make a copy of the Button and drag the Button upward vertically, just below the ListBox. Release the mouse button when the horizontal alignment guide appears. Adding the Delete button. In the Controls pane, hold down the mouse button on the TextField and drag it into position in the window, midway between the Delete and Connect buttons. Grab the right-center handle of the TextField and enlarge it so that its right side aligns with the ListBox and the two Buttons (see below). Aligning the right side of the TextField with the ListBox and the Buttons. Align the left edge of the TextField with the left edge of the ListBox. (Optional) If you find that the top Button, the TextField, and the bottom row of Buttons are not evenly distributed, you can reposition a control by clicking on it and moving it one pixel at a time using the Up or Down arrow keys.

Your application’s interface is now complete!

It should look as shown below.

Before going any further, save the project.

• Choose File ↠ Save (Ctrl+S or ⌘-S) and name it “URL Manager”.

At this point, you can actually try it out. Of course it won’t do anything since we haven’t told any of the interface elements what to do.

• Just for fun, click the Run button in the Main Toolbar.
  Real Studio builds the application and opens it in your default web browser.
  The first version of the application should look like this:
  

In this state, the Buttons work — that is, you can click them and they highlight — but they don’t do anything because we haven’t told the Buttons what to do when they’re clicked. You can enter text into the TextField — but it doesn’t go anywhere because there are no instructions to process this text. And the ListBox is all set to display and scroll items but we don’t have any way to get text into the ListBox yet.

Switch to the Real Studio IDE and click the Stop button below the row of tabs. This closes the Web application, which is running in your default browser.

Giving Objects Meaningful Names and Labels

You’ve already noticed that all the Buttons use the default label “Untitled.” They also have default names like Button1, Button2, etc. Before getting too far into the project, we should give the objects meaningful names and labels. You refer to the object’s names in your Real Studio code and, of course, the labels are presented to the user. You should give each object that you refer to in your code a meaningful name at the start of the project.

Click on the surface of the webpage in the WebPage Editor — not one of the controls on the page — and then take a look at the Properties pane. The WebPage has the default name “WebPage1” which is shown in the first line. If it shows some other name, then you clicked on one of the controls in the WebPage rather than the surface of the WebPage itself. WebPage1’s Properties pane. The text that appears in the Title bar of the WebPage is the Title property. The Name property is the name of the WebPage that you use in your code to refer to it. Select the default Title, “Untitled”, in the Properties pane and replace it with the text “URL Manager”, and press the Enter key (Return on Macintosh). When you press Enter or Return, the new title appears in the Title bar of the WebPage Editor as well as in the Properties pane. Changing WebPage1’s Title property. Similarly, we need to replace the default names and labels for the controls in the WebPage. In the WebPage Editor, select the Untitled button in the lower left corner by clicking on it. Notice that the Properties pane changes to show the properties of this Button. The three Buttons are named Button1, Button2, and Button3. They were named in the order they were created. We’ll never remember which one is which, so it’s best to rename them at the same time we’re entering their labels. Change this Button’s Name property to “AddURL” and its Caption property to “Add”. Press Enter (or Return on Macintosh) after typing each entry to save each new property value. Notice that the Caption text immediately replaces “Untitled” in the WebPage Editor when you press Enter. When you are finished, the Properties pane for the AddURL Button should look like this. The Properties pane for the Add button. Click on the Untitled button in the lower right to select it. It’s Button2. Use the Properties pane to change its name to “ConnectURL” and its Caption property to “Connect”. Click on the Untitled Button between the ListBox and the TextField. Change its Name property to “DeleteURL” and its Caption property to “Delete”. Click on the TextField and change its name to “SelectedURL”. Click on the ListBox and change its Name property to “ListURL”. That takes care of it. The Properties panes for these objects should look as shown below. The Properties panes for the other controls. Check your work to be sure that the items are named correctly. If there is a spelling error in a Name property, the code that is supposed to refer to that item will not work. In the WebPage Editor the three buttons should now look like this: The three Button controls after renaming. Choose File ↠ Save to save your changes. Click the Run button in the Main Toolbar to test the application. Real Studio launches your default browser application and runs the Web application in the browser window. It doesn’t do any more than the last version, but at least all the interface elements are labeled correctly. When you are finished testing the application, switch to the Real Studio IDE window and click the Stop button below the row of tabs.

Making the URL Manager Do Something

Now that the interface is designed and its appearance is touched up, it’s time to make the controls do their jobs. We’ll start with the Connect button. You specify the action that a button carries out by writing some code that becomes a part of the button.

In the WebPage Editor, double-click the Connect button. The Code Editor for WebPage1 appears. This is where you write code for the WebPage and the controls contained on the WebPage. On the left side is a browser area that lists all the controls that we’ve added to the window, among other things. (For the Web Tutorial, we only need to work with the controls.) The large area right is the code editing area. It holds the code for the item that is selected in the browser. Right now the “Action“ item for the Connect button is selected. It’s highlighted in the Browser area and the header area above the editor gives the name of the event. The Code Editor for the Connect button. In order to get the Connect button to do something, we need to write some code that will run only when the user clicks this button. Fortunately, the Real Studio application itself monitors all user interface activity while the application is running and it knows whenever this happens. To make the Connect button work, we need to write the instruction that connects the user to the web site that the user enters into the TextField. In the Browser area of the Code Editor, you’ll see a list of events that Real Studio continuously monitors while the application is running. For example, the MouseEnter and MouseExit events are triggered when the mouse pointer enters the region of the Button and leaves that region. The event we need is the “Action” event. This event takes place when the user clicks the button. On the right side of the divider, you can write the code that runs automatically when the user clicks the button. (Notice that the top line, “Sub Action()”, indicates which event the code is for). The instruction to open a web site in the user’s browser (or open the email application) is simple. The instruction is ShowURL and its syntax is: ShowURL string Where string is the URL (or email address). As soon as you enter “ShowURL”, the syntax for this command appears in the Tips bar. By referring to the Tips bar you can avoid having to look up a command’s syntax in the Online Language Reference whenever you need help. The Tips bar showing the syntax for ShowURL. To test out this button, enter the following line in ConnectURL’s Action event: ShowURL "http://www.yahoo.com" Be sure to enclose the URL in quote marks. The quote marks indicate that the text in quotes is a string (rather than a number or some other type of data). Your Code Editor should now look like this: The code for ConnectURL's Action event. Click the Run button in the Main Toolbar to test the Connect button. When the Web application appears, click the Connect button. In a few moments, your default web browser will open a new window and bring up the WebPage you entered. (This, of course, assumes your computer has a connection to the Internet and you have a default web browser application.) The Yahoo home page. Of course, we need to modify the code so that the text passed to the ShowURL command can be entered by the user while the application is running. When we use ShowURL "http://www.yahoo.com", the particular URL is “hardcoded.” Note: If you get a syntax error, check to make sure that you spelled the ShowURL command correctly, that you enclosed the URL in double quote marks, and that it is a valid URL. Close the browser window to return to the Real Studio IDE. We now need to replace the text used with the ShowURL command with the code that refers to the contents of the TextField, SelectedURL.

Since the TextField is named “SelectedURL”, you might think that we could write:

but that won’t work because “SelectedURL” is the name of the object itself. It has lots of properties — like its position in the window, whether it takes several lines of text or just one, whether it can accept styled text, and so forth. If you use “ShowURL SelectedURL”, Real Studio would have no idea what you mean. Besides, the ShowURL command only accepts a text string, not a control. When you need to refer to one of an object’s properties, you write the name of the object, followed by a dot, followed by the name of the property. In other words, you use this syntax: objectname.propertyname. It’s sometimes called “dot” notation. In this case, the TextField is named “SelectedURL” and the TextField property that we want is its “Text” property. This means the following expression accesses the contents of the TextField:

That is, “SelectedURL” is the name of the object and '“Text” is the name of the object’s property that we need.

In the Code Editor for the Action event, modify the code to read: ShowURL SelectedURL.Text This expression SelectedURL.Text refers to the Text property only. Your Code Editor should now look like this: The revised code for the Action event. Save the project (File ↠ Save) and test it by clicking the Run button in the Main Toolbar. The URL Manager application opens in a new browser window. Enter a URL in the TextField, such as http://www.realsoftware.com and click Connect. Your default web browser should open the web page you entered. When you’re finished,close the browser window to return to the Real Studio IDE.

If the Application Doesn’t Run

If Real Studio was unable to launch the debugging application, it’s because it couldn’t recognize a term you entered into the Code Editor. For example, if you misspelled either “ShowURL” or “SelectedURL”, Real Studio stops and points out the term it doesn’t recognize. Instead of compiling and launching the application, it opens a new “Issues“ tab in the IDE. It has one line per issue. For example, the following shows a spelling error.

The misspelled term is highlighted. Double-click the line to go to the editor with the error. In this case, Real Studio displays the Code Editor for the ConnectURL Action event, show below. The line that contains the error has a bug icon to its left.

Since it can’t find an object called “SelectURL,” it can’t create the application for you. Real Studio knows it would never be able to figure out what to do when a user clicks the Connect button. Be sure you’ve renamed the controls as described and referred to their correct names in the Code Editor. You’ll also get this error if you wrote “ShowURL SelectedURL” and left off the name of the property that contains the contents of the TextField.

Another possibility is that you used the correct name in the Code Editor but did not rename the TextField using the Properties pane as shown earlier. In that case, the statement in the Code Editor ought to work, but there is no object named “SelectedURL” in the application. If you get an error message, start by checking the highlighted term. Now, we’ ll make the other controls do their jobs.

The Add Button

The Add button is supposed to take the text in the TextField and add it to the end of the list in the ListBox. That’s easy.

If the Code Editor for the window is not already open, double-click the Add button in the window (If the WebPage Editor is not shown, click the WebPage1 tab in the Tabs bar). Enter the following code into the Add button’s Action event: ListURL.AddRow SelectedURL.Text The first part of the expression, ListURL.Addrow calls a built-in method belonging to a ListBox. The AddRow method is a command that adds a row of text to the end of whatever list is already in the ListBox. Not surprisingly, it needs to be passed the text of the new item. We already know that SelectedURL.Text refers to the contents of the TextField, so that is what we use.

Note: A method is a command that performs an action. Technically, ShowURL is a “global method” because it isn’t attached to any particular object. It can be called by any object that can call a method. We just happen to be calling it from a Button. (We could, for example, design the application so that ShowURL is called when the user chooses a menu item instead of clicking a button.)

Just as objects can have properties (like their name, size, position, and label), they can also have their own methods. AddRow is also a method but it “belongs” only to ListBoxes. It has a specialized action that only makes sense when applied to lists in ListBoxes.

The Delete Button

The Delete button removes the selected item in the ListBox. It’s also pretty simple.

In the Code Editor, expand the DeleteURL item and highlight the Action item. Enter the following line of code: if ListUrl.ListIndex > -1 then ListURL.RemoveRow ListURL.ListIndex

In this case, we are calling the built-in RemoveRow method of the ListBox control. Instead of text, it needs the number of the row (line) to delete. The ListIndex property contains that number, so we pass that number to the RemoveRow method.
Note: If you place the insertion point in the RemoveRow term, the Tips bar will say that RemoveRow requires that an integer be passed to it.

The ListBox

The ListBox itself has the job of copying the item the user selects into the TextField so the user can connect to that URL or email address. You can do this by writing an assignment statement that runs when the user highlights an item in the list.

In order to do this, you need to get the item that the user has selected in the ListBox. You can get this text, but the process uses two of the ListBox’s properties.

First, the property “List” is the list of all the items in the ListBox. You need the one that the user highlights, not all of them.

The seond property is the number of the selected item, not its text. Real Studio determines which one is selected for you and you can use it to get the text of the selected item. The number of the selected item is in the ListIndex property. The first item is numbered zero. (Thus, this is called a zero-based array.)

The List property needs only the number of the selected item. You get that information from the ListIndex property and hand it off to the List property to get the text of the selected item.

The expression as a whole gets the text of the selected item and assigns it to the Text property of the TextField. It is:

Expand the ListURL item in the Code Editor browser area and select the SelectionChanged event handler. The SelectionChanged event runs whenever a different item in the ListBox is highlighted. Enter the following code into the SelectionChanged event: if ListURL.ListIndex > -1 then SelectedURL.text = ListURL.List(ListURL.ListIndex) else SelectedURL.text = "" end if

Testing the Application

That’s the basics of the application. Now it’s time to test out all these features. Before you run your project again, you can ask Real Studio to check the project for errors or ways to optimize your application. You use the Analyze Project command. Analyze Project uses Real Studio’s compiler to review all of your code and identify any coding errors. It also offers suggestions on how to improve your application.

Choose Project ↠ Analyze Project. If it finds no issues, it displays a message box with the message, “Check passed; no issues were found”. If Analyze Project finds any issues, it opens up an “Issues” panel and lists the problems. If there are several issues, they are organized by type of issue. Click the disclosure triangle to the left of the error message to view the specific errors. Details of a spelling error. (If needed) Double-click each error message and fix the error before proceeding. Click the Run button in the Main Toolbar to test the application.

The application looks the same as it did, but all the controls work! For example, enter “http://www.realsoftware.com” into the TextField and click the Add button. Add a few other URLs to the ListBox in this manner and then highlight one in the ListBox to move it to the TextField.

You can:

• Enter a URL into the TextField and connect to the site using your default web browser.
  
• Add the URL to the ListBox.
  
• Select any URL in the ListBox to copy it into the TextField.
  
• Delete the selected URL in the ListBox.

If you want to send an email, enter it in the following way: mailto: username@domain.com

Using Autocomplete

One way to avoid using incorrect terms is to take advantage of Real Studio’s “autocomplete” feature. As you type, Real Studio tries to guess what you are typing. If you type the first few characters of a Real Studio language object — either built-in or a variable, method, or property that you created — it shows its guess in light gray type. If the guess is correct, press the Tab key to complete the entry.

If there is more than one possibility, Real Studio displays a contextual menu when you press Tab. Here is an example:

The user has just typed “ListURL.L” and pressed the Tab key. Real Studio displays a contextual menu with all the possible terms that complete the expression. Use the Up and Down arrow keys to navigate through the list and then press the Enter key (Return on Macintosh) to select the highlighted term.

The small icons to the left of the term tell you what type of object it is. In this case, the checkmarks indicate that the items are boolean properties and the 1’s indicate that they are integer properties.

If the Application Doesn’t Run

This section introduces the If…Else…End if statement. The Code Editor automatically indents the code within an If statement to make it easy to check your code. Be sure that your code is indented as shown in the instructions. Be sure there is an “End If” statement for each “If” and you didn’t type “Endif” instead of “End if”. Capitalization doesn’t matter, but the space between “End” and “if” does. Also, check that each line that begins with an “If” statement ends with “then”. Also, you should not leave a blank space between the double quote marks or between the less than and greater than signs.

Building A Standalone Application

Now that you have a finished version of the application, you’re ready to create a standalone web application. The standalone version of the application is ready to be deployed as a web application.

The Enterprise and Web versions of Real Studio can create standalone Web applications from any desktop platform. The Personal and Professional versions of Real Studio build demo Web applications. A demo version is fully functional but quits automatically after five minutes and cannot be saved as a project.

You can build a Web application that is served by any desktop platform that is supported by the Desktop Version. By default, Real Studio builds for the platform that you are currently running. If you want to cross-compile for another desktop platform, you can make that choice by choosing Project ↠ Build Settings. The following dialog box appears:

This dialog box has two panels. On the General panel you choose the platform from which the Web application will be served. You must configure your Web server to work with this app.

On the Web panel, you choose the type of Web application that you want to be served. It can be a CGI or Standalone HTTP application. You must configure your web server to serve the type of application that you build.

The choices are shown in the Web panel of the Web Settings dialog box.

Deploying the built Web application requires that you configure your Web server. This is beyond the scope of this Tutorial; Chapter 15 of the User's Guide contains instructions for a configuring an Apache server running on any platform and instructions on how to configure Microsoft Internet Information Server 7 (IIS) on Windows.

Building a stand-alone version of your project as an application couldn’t be easier than it is in Real Studio.

Click the Build button in the Main Toolbar. When you create a standalone application, Real Studio creates a new folder and creates the standalone web application. The folder containing the built Web. By default, it uses the name “My Application”.

What’s Next

The Web Tutorial shows how easy it is to develop a simple Web application. But there is much more to Real Studio. The second Real Studio Tutorial builds the URL Manager as a Desktop application. You will see the same Integrated Development Environment, but the design and layout tools are for building cross-platform Desktop applications.

Real Studio is a fully object-oriented development system. With it you can create classes (reusable objects) that encapsulate custom functionality. You can add them to the project so that they can be reused in many places in the project and save them to disk. In the User’s Guide, you will learn about the object-oriented development system in detail. The Language Reference is a comprehensive listing of all the programming elements in the Real Basic language.

Also, be sure to check out the example projects that ship with Real Studio and the Real Studio web site at http://www.realsoftware.com for other tutorials and how-to’s.