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 069

Review: REALbasic 4.5 (Part 3)

Last time we looked at the new vector graphics feature of REALbasic 4.5. This week we continue with a look at some more new features of RB 4.5.

Better Mac OS X Support

One of the most significant new features of REALbasic 4.5 is improved support for Mac OS X. These improvements are reflected over a number of features.

Preferences Menu

Have you ever seen a program with two Preferences menus, one active and one inactive? That was probably created in an earlier version of REALbasic. Mac OS X automatically adds a Preference menu, but REALbasic gave the programmer no way to access that menu (activate it or remove it). If the program already had a preferences menu, the program would end up with two: one added by Mac OS X and one by the programmer.

There were some third party solutions (plug-ins) or OS calls (declares) one could make to workaround this problem, but it wasn't easy. But new to RB 4.5 is an elegant and simple solution: the PrefsMenuItem class. This is a special type of menu: REALbasic knows it's your app's preference menu and under Mac OS X will move it to the Application menu and activate it (as per Mac OS X interface guidelines). Under Classic or Windows, the menu will stay where you put it.

To use this feature, simply select your preferences menu item on the menu in your project, and give it a super of PrefsMenuItem on the Properties palette:

That's it! Now when you run your program, REALbasic will do the appropriate thing under any OS and you don't have to worry about it.

Sheets

Another new Mac OS X feature for RB 4.5 is support of "sheets," those Mac OS X dialogs that slide down from the top of a document window. The advantage of sheets is they stick with a particular document. For instance, you could implement a "Close without saving?" dialog as a sheet and the user could leave the document open while editing a different file. A traditional dialog would have to be dismissed before the user could do anything else within that application.

To use a sheet in REALbasic, you need to do two things. First, you must specify its frame as a sheet within the Properties palette. Second, when you tell the dialog to open, you don't use showModal, you use showModalWithin. Like this:

 notSavedDialog.showModalWithin self 

That's pretty much it from a technical side, though you might want to read up on Mac OS X interface design to make sure you use sheets appropriately.

Miscellaneous Improvements

There are a few less obvious but convenient niceties REAL Software has thrown in, such as support for long file names, package support in file dialogs, and new properties for the screen object (availableHeight, availableWidth, etc.) which tell you the actual screen real estate available taking into account the space the Dock uses (see last week's letters for an example of this feature).

Non-Mac OS X Enhancements

Don't use Mac OS X yet? Not to fret: besides major new features to the language, there are some small things that will help every user. Not all the new features are exclusive to Mac OS X.

Unhandled Exception

Exceptions are severe REALbasic errors that cause your program to quit. An exception might be referring to an object that doesn't exist (it is nil) or accessing beyond the end of an array (if you've defined an array as dim a(10) as integer you will get an exception if you attempt to put something inside a(11)).

Ideally, you should include error checking code in your program to check for possible error conditions (such as confirming the object isn't nil before using it), but unfortunately that can be difficult as the range of possible errors is high. Since you can't possible foresee every potential error, you can use REALbasic exception system to handle exceptions. REALbasic's default approach is to put up an error dialog and quit the program. If you handle it yourself, however, you can give the user other options besides simply quitting.

Unfortunately, a long-term criticism of REALbasic's exception system is that you had to add code for exceptions in every single block of code. That meant a lot of error code duplication (handling the same errors in different sections) and so much work that few programmers bother.

With REALbasic 4.5, however, REAL Software have added a new event to the application class object. This event is called unhandledException and you can use it to catch any exceptions you don't catch anywhere else. If you return true to this event, you're telling REALbasic that you've handled the event and it doesn't have to do so. This is a much needed addition to the language and should help make REALbasic programs more stable. If you use it, that is: do so.

In Detail

Remember, to access the application object of your program, you need to add an application class object to your project. Simply add a new class (File, "New Class") to your project. I usually name mine app, but you can name it whatever you want. For the super of the object, set it to "Application" on the Properties palette. After that, you can access any of the properties of your application by name (i.e. app.shortversion) and if you open the object, you'll find all of its events (many, like OpenDocument and HandleAppleEvent are unique to the application object).

Application Class Properties

In addition to the new unhandledException event, there are also some new properties in the application object. You can now access the version information of your application:

This is a great addition. It's standard practice to display a program's version info to the user in the About Box, and for many programs it might be appropriate to access this info in other areas (for instance, you could save the program's version info in the files your program saves so future versions of your program could know which version of the program created the file). However, while this info is put in REALbasic's Build Settings dialog, it is difficult for your program to access it.

For those of you who've been following RBU for a while, you'll remember that my technique for handling this problem is to put it in a constant. However, this means you must keep the version details in two places: in your constant and in the Build Settings dialog.

By adding convenient properties to the application object, you can now easily access not just version info, but region info and other details.

Well, that's it for this column. Next we'll continue by looking at some more big improvements in RB 4.5.

Next Week

We continue covering more of RB 4.5's major new features.

News

The October/November issue of REALbasic Developer hits the stands next week and here's a brief preview of what's inside:

Doing Undo, by Scott Forbes

A detailed exploration of creating an OOP-based undo system for your application. I guarantee you'll learn something from this article.

Postmortem: UniHelp

UniHelp just won a Cubie and it's one of the hottest programming tools for REALbasic, making adding help to your application a snap. Learn what it took to create UniHelp.

Basic 3D Math, by Joe Strout

Don't know what a vector is? Then this is the article for you. Even I can understand it!

Interview: Dick Dinkelspiel

Using REALbasic, Dick created the $289 TitleTrack Jukebox, a unique combination of hardware and software that controls Sony CD changers and lets you mix your CD collection with MP3s on your hard drive.

Plus there's a new database column, how to create Mac OS X bundles, sorting algorithms, wrapper classes, using the UNIX shell, Apple Events, Q&A, reviews, news, and tons more.

New subscriptions placed in October will be mailed the second issue at the end of the month. (Current subscribers will receive their copies in October.)

Back issues of the premiere issue are available for individual ordering.

Letters

Today we've got a sprite question from Florian + Matthias:

Dear genius!

I wondered if it was possible to tell realbasic's sprite control to get the location where the user clicked (and released) the mouse button and to move a certain animation (like in the column walker) from different points to the point the user clicked on!

  
 
 if yes then 
 
    msgbox "please tell me how" 
 
 else 
 
    msgbox "darn!" 
 
 Endif 
 
  

Thanks a lot and regards,

The regular readers of your column, Florian + Matthias

Sure, this doesn't sound too difficult. You may have to do some calculations to convert between various coordinates, however. In the simplest setup, assume your spriteSurface is the same size as your window (full screen). The click would send a mouseDown to the window, which you could return true to so that you could receive a mouseUp.

Within the mouseUp event, you'd put in code to move your sprite. You already know the sprite's position, so it's just a matter of calculating how to move to the new position. If the spriteSurface and window are the same size, the x and y coordinates passed to mouseUp would be in the same coordinate system as the spriteSurface, so you'd only need to do a little subtraction. If the spriteSurface is smaller or larger than the window, you'd need to adjust for that in your calculations.

While I didn't try this with a sprite, I did create this test program which will display a dialog with the x/y coordinates of where you click.

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

.