REALbasic University Resources: RBU: Glossary Defines common REALbasic programming terms   Archives Previously published columns Translations: Dutch Courtesy of Floris van Sandwijk   Japanese Courtesy of Kazuo Ishizuka   Chinese Courtesy of Dong Li   RBU Translation Guide Information on Translating RBU into other languages Books: Matt's Book (2nd Edition!) Ideal for experienced programmers   Erick's Book Best for beginning programmers Websites: Mother Ship The publisher of REALbasic   RB Webring Links to hundreds of REALbasic websites   RESExcellence Another REALbasic programming column   REALbasic Developer Magazine The premiere source for REALbasic instruction. REALbasic University is Sponsored by Make your Mac do what YOU want it to. Create games, utilities, cool Mac OS X tricks. Download REALbasic now and create your own software.

REALbasic University: Column 074

DoRbScript: Part IV

Today we'll get to test our program, DoRbScript, and see if it works, by writing an AppleScript that will send it an RbScript and post the response.

Creating the DoRbScript Application

Before we can write our AppleScript, we need a program for it to talk to. We can't test AppleScriptability within the REALbasic IDE -- we must compile DoRbScript into a stand-alone application.

Before we do that, we must give DoRbScript a unique four-character Creator type. That's because AppleScript figures out which application we're talking to by the Creator code. If more than one program had the same Creator type (i.e. the default of "????"), the AppleScript might not talk to the correct program. When you create a program, be sure to register your unique creator code with Apple so no other program uses that same combination of characters. (That's also why we can't talk to our app within the IDE: we'd be talking to the IDE, not our program.)

Open your DoRbScript.rb project file within REALbasic. Choose the "Build Settings" command on the File menu. You can build for Mac OS X or Classic (it doesn't matter), but you need to give your app the correct Creator type. I've registered "DoRb" (remember, case is significant) with Apple, so it's safe to use that (it shouldn't be used for any other program out there).

Once you've set the creator, we're ready to compile. Click OK to save the "Build Settings" settings, and then choose "Build Application" from the File menu. You should end up with either a Classic or Mac OS X executable (or both).

Go ahead and run the program (double-click on it). You'll notice it doesn't appear to do much: it just sits there. That's perfect. Now let's write some AppleScripts!

Testing AppleScriptability

To write an AppleScript, we need to launch Script Editor (it should have been included with your OS install -- do a search if you can't find it). If you haven't used Script Editor before, don't worry: it's just a simple text editor with a Run command for executing AppleScripts. It's similar to REALbasic's Code Editor:

Let's write a very simple AppleScript to test and see if our program works. Put this into Script Editor:

  
 
 tell application "DoRBScript (Mac OS X)" 
 
    copy |DoRBScript|("print str(5 + 3)") to theThing 
 
 end tell 
 
  
 
 display dialog "The result is " & theThing 
 
  

Important: Note the name of the application I've used. If the name of the app you compiled a moment ago is different, you'll need to change the name in quotes here to match the name you used.

Once you've got this code input, save the script as "Simple Script" (or something) and let's run it (click the "Run" button). You should almost immediately see a dialog like this displayed:

Yeah! It worked! This means we successfully talked to our DoRBScript program and passed it an RbScript command which it processed and returned to us the result.

(If it didn't work, you'll need to figure out if the error is in your AppleScript or within DoRBScript. That could get complicated, so I won't go into how to figure that out here. You might try downloading the finished project and comparing it to yours to see where you made your mistake.)

What, exactly, did our AppleScript do?

First, you'll notice we enclosed our command within a "tell" statement. A tell statement is AppleScripts way of talking to a specific application. For instance, the Finder (a scriptable app) doesn't understand the DoRBScript command. But by telling AppleScript to send that command specifically to "DoRBScript (Mac OS X)" the command is interpreted by a program that understands the command.

Within the tell statement, we use the "copy to" command to send the results of the DoRBScript command to a variable called theThing.

The DoRBScript command itself is the most interesting. Remember when we set up our aete resource we established that our DoRBScript command would take a text parameter and return a text value? Well, here we're just passing it a text parameter:

"print str(5 + 3)"

That's a very simple RbScript. Remember, the only results we get are those passed via the print command, so with a one line script like this, we must include a print instruction or we'd see no result! Since our math problem is dealing with numbers and our result must be text, we coerce the 5 + 3 math result to a string with the str() function. That result is "printed" -- which is what is returned to our AppleScript (and stored in theThing).

The final line of the script simply displays a dialog with our result.

But one line RbScripts aren't very useful. How would we go about doing something more sophisticated?

The Test AppleScript

There are a couple ways to get the RbScript that we send to DoRBScript. The simplest is to build it within Script Editor, like this:

As you can see, we build the script line by line, appending to a string variable, rb. Eventually rb contains the full script. Note that the "return" in the above is an AppleScript term that is a carriage return character (easier than using chr(13) in a REALbasic program).

The above script is a graphic, so you can't copy the text. Here's the raw code (note that it won't display properly as an AppleScript since my source code display system is set up for RB code):

  
 
 -- Build the script 
 
 set rb to "dim i, n as integer" & return 
 
 set rb to rb & "for i = 1 to 1000" & return 
 
 set rb to rb & "n = n + i" & return 
 
 set rb to rb & "next" & return 
 
 set rb to rb & "print str(n)" & return 
 
  
 
 -- Execute the script 
 
 tell application "DoRBScript (Mac OS X)" 
 
   copy |DoRBScript|(rb) to theThing 
 
 end tell 
 
  
 
 display dialog "The result is " & theThing 
 
  

If you've done everything correctly, you should end up with a result dialog like this when you hit Run:

As you can see, this is a more complex example: we've reserved variables (the dim statement) and used a for-next loop. Pretty cool! There's a lot of power in RbScript, and this is a fun way to try it out. You can use DoRBScript as a simple way to extend the power of AppleScript.

For more power (i.e. longer, more complex RbScripts), you could have the AppleScript load the script from a text file. That would be easier than a mile long series of "set rb to rb &..." statements. But I leave that as an exercise for you to figure out. (O'Reilly publishes the excellent AppleScript in a Nutshell if you need more AppleScript advice.)

If you would like the complete REALbasic project file for this week's tutorial (including AppleScripts and other resources), you may download it here.

Next Week

We review the new book, Learning REALbasic Through Applications.

Letters

This week we've got a question on sorting from Valerie.

Hi!

I'm new to RB and so far your column help a lot... I have not gone through all of it so maybe the answer to my question is somewhere in there. But here it is anyway:

I want to sort the second column of my listbox, I try with listbox.column(1).headingIndex=0, with .sort, with columnSortDirection but nothing seems to do it.

Thanx!
Valerie

You don't mention which version of REALbasic you're using, Valerie. In 4.5, things changed a bit. You used to do it with the .headingIndex property, but now we use the pressHeader method:

 listBox1.pressHeader(1) 

I built a simple project to demonstrate:

There are two ways this can be sorted by the second column. First, if the user clicks on the second header, it's automatically sorted. A second click sorts it in reverse order:

However, it sounds like you want to sort it programmatically (via code). Easily done. The code for the "sort by second column" button is this:

 listBox1.pressHeader(1) 

But there's even more we can do. What if the you want to control the direction of the sort? Well, you set that with the listBox1.columnSortDirection property. I've added a "toggle sort dir" button to my project that reverses the direction of the sort. Here's what that code looks like:

  
 
   if listBox1.columnSortDirection(1) = 1 then 
 
     listBox1.columnSortDirection(1) = -1 
 
   else 
 
     listBox1.columnSortDirection(1) = 1 
 
   end if 
 
    
 
   // After toggling, we could automatically resort 
 
   // so the user sees something happen 
 
   sortButton.push 
 
  

Note that the listBox1.columnSortDirection property requires a parameter telling it which column we're sorting. In this case it's column 1, the second one.

Hopefully this should clarify things. You can download my demo project here.

Each week we answer select reader questions, and we're always open to ideas for future columns. Send your questions to . (Keep your questions simple and specific. General queries like "How do I write my own web browser?" will be neglected.) Your question won't be answered immediately, but will be answered in a future column. (If you don't want your correspondence published, just be sure to indicate that when you write. Otherwise it's fair game.)

About the Author
is an author, philosopher, graphic designer, photographer, film director, soccer fanatic, and programmer (among other things). He writes for MacOpinion, runs his own software company, Stone Table Software, which sells the revolutionary Z-Write word processor, and is Publisher and Editor of REALbasic Developer. He lives in Northern California with his cats, Mischief and Mayhem, and is rapidly running out of free time.

See the REALbasic University Archives

.