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 104

OOP University: Part Twenty-Six

Today I show how to use the universal progress dialog we created in our last lesson.

Working with ProgressDialog

It's great being finished with the project, but we really can't test it without coming up with a way to use progress bars. So I've created a test application.

The basic steps to using progressDialog are the following:

1. Call the init routine and establish the kind of window we'll need.
2. Call startProgress routine (and startSubProgress if it's a dual-bar window).
3. Begin your task.
4. Periodically during the task, make calls to updateProgress and updateSubProgress to let the user know what's going on.
5. Periodically during the task, check to see if gPleaseStopProgress is true, and if it is, stop the action.
6. When the operation is finished or the user has cancelled, call stopProgress.

While this may seem daunting when you first see it, it's actually far less code than you'd have to write to support a progress dialog manually. Generally each of these is just a single line of code, so the library's very simple to use.

For example, here's some code to test a single progress bar dialog:

  
    dim i as integer 
    dim s as string 
     
    const bigNum = 1000000 
     
    // Init progressDialog 
    progressDialog.init("Single bar count", true, cancelCheck.value) 
    progressDialog.startProgress("Counting...", bigNum \ 1000) 
     
    for i = 1 to bigNum 
      // if evenly dividable by 1000 
      if i / 1000 = i \ 1000 then 
        s = "Item " + str(i) + " out of " + str(bigNum) 
        progressDialog.updateProgress(s, 1) 
      end if 
      if cancelCheck.value and gPleaseStopProgress then 
        progressDialog.updateProgress("User aborted...", bigNum \ 1000) 
        exit 
      end if 
    next // i 
     
    // All done, so get rid of dialog 
    progressDialog.stopProgress 
   

This just uses counting to a million as our task, and displays the progress as we go along. Notice that we divide number by 1000 so we're only updating the progress bar occasionally -- if we update the progress bar for every step on the way to a million, it'd take forever (the progress bar slows things down a great deal).

This example uses a checkBox control to set whether or not the dialog is cancellable (that's the cancelCheck control). If it's cancellable, then we check our global property, gPleaseStopProgress, to see if the user has cancelled the action. The actual detection of the cancel event happens within the dialog, but since the dialog can't actually halt the action, you must put checks within your task to have it stop if it notices the action has been cancelled.

As you can see, calling the routines of our reusable progress bar dialog is simple and efficient, and it works great. We can easily modify this routine to two counting loops and test out a dual progress bar dialog:

  
    dim i, j as integer 
    dim s as string 
     
    const outerNum = 10 
    const innerNum = 100000 
     
    // Init progressDialog 
    progressDialog.init("Dual bar count", false, cancelCheck.value) 
    progressDialog.startProgress("Counting...", outerNum) 
     
    for i = 1 to outerNum 
      s = "Item " + str(i) + " out of " + str(outerNum) 
      progressDialog.updateProgress(s, 1) 
       
      progressDialog.startSubProgress("Counting inside", innerNum \ 1000) 
      for j = 1 to innerNum 
        // if evenly dividable by 1000 
        if j / 1000 = j \ 1000 then 
          s = "Item " + str(j) + " out of " + str(innerNum) 
          progressDialog.updateSubProgress(s, 1) 
        end if 
        if cancelCheck.value and gPleaseStopProgress then 
          progressDialog.updateSubProgress("User aborted...", innerNum \ 1000) 
          progressDialog.updateProgress("User aborted...", outerNum) 
          exit 
        end if 
      next // j 
       
      if cancelCheck.value and gPleaseStopProgress then 
        exit 
      end if 
    next // i 
     
    // All done, so get rid of dialog 
    progressDialog.stopProgress 
   

This should be self-explanatory. It's just like the other one, except there are two loops.

Now you may find that this progress bar system won't work in all situations. But this is only one way to implement a progress bar. In our next tutorial I'll cover some other approaches, including using threads!

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

Next Week

Other approaches to a progress bar dialog.

News

REALbasic Developer 2.1 August/September 2003 Published

The latest issue of REALbasic Developer magazine is now available! The August/September issue features at ton of great stuff.

First, have you heard the exciting news that the next version of REALbasic will support compiling to Linux? RBD has an exclusive interview with the folks at REAL Software and we get the 411.

Speaking of REAL Software, many of you have probably heard David Grogono's name or exchanged emails with him, but exactly who is he? Our interview with REALbasic Product Manager David Grogono reveals all. Find out how he left a life as a sailboat captain to captain REALbasic.

3D guru Joe Strout is back, this time with wild real-time mesh deformations. His example project shows how to simulate cloth flapping in the wind. It's impressive.

Then we've got a double bill from Charles Yeomans. First he explains what you need to know about REALbasic 5's new Extends and Assigns keywords, and then he's got an excellent article on how to add a neat "recent items" menu to any program.

And of course along with those articles we've got news, reviews, and all our regular columnists!

Subscribers should be receiving their issues this week, and if you aren't a subscriber, become one! You can even order all the back issues if you don't want to miss anything.

Letters

This time we've got a question about compiling for Windows from Richard Davis:

Hi,

I have very recently downloaded a demo of RB5.2 for OSX. I have absolutely no programming experience and hope to learn quickly. My goal is to develop applications for myself and my Windows-using friends. I have read some comments about RB's less than perfect Windows output. I'm after an unbiased view of how good RB is for producing apps for Windows. I have Visual Basic 6 for Windows so I could buy the standard edition of RB for my Mac development and learn VB for Windows.

Many thanks

Richard Davis

This is a complex question, Richard. While I don't have much experience developing for Windows, here's my take on the situation. Your mileage may vary.

Simple apps seem to work great. Press compile and you've got an .exe that runs under Windows. With more complicated projects, however, you'll have to do some extra work. Sometimes this extra work is simple platform differences such as the way files are handled and with a little planning you can easily create a multi-platform application.

Other times you'll find that there are slight differences in how controls respond, the order or manner in which events are handled, etc. It can take some tweaking to work around a problem and get it to work exactly the same on both platforms.

The extent of the difficulty depends on many factors, including the specific bugs/problems you are encountering and how picky you are (there's a huge difference between developing an app that runs and a polished app that fully follows all the user-interface guidelines of each platform).

In general, planning is the key. If you work from the beginning to develop a cross-platform application, making sure as you write each routine that it works on both systems, and do your best not to make platform-specific assumptions (easy to do if you're not intimately familiar with a target platform), your program will run on both systems just fine.

For instance, as a longtime Mac user, I tend to think of Mac-only solutions without even realizing it. If I'm trying to solve a problem I might think, "Hey, I can do that with an AppleScript!" Unfortunately, of course, AppleScripts don't run under Windows, so that wouldn't be a good solution for a cross-platform app. The reverse is also true: ActiveX controls won't work on the Mac.

Another example of my Mac-centric way of thinking: back when I created my first "real" cross-platform app, RBU Pyramid, I included graphics that were in a Mac format. While that worked fine on the Mac, the graphics didn't work on the PC. I had to save them as .bmp files for them to work there. Not a big problem, but one of those things you have to think about.

Having a REALbasic IDE that runs under Windows is a huge boon to the cross-platform developer. In the past we had to compile only on the Mac and move the .exe to Windows for testing, a rough road for rapid development. Now we can develop on either platform for either platform, and that makes things considerably easier. You can do rough development on the platform of your choice, then take your project file to the other platform for tweaking.

Practice also helps. The more cross-platform apps you create the more you're aware of any potential pitfalls and you can avoid them.

Understand that there's nothing inherently wrong with REALbasic's cross-platform support. While there are some bugs and problems, these mostly fall into the category of minor visual or operational differences. They're not a problem in most situations, but if you're doing something complicated, you may find you need to time to figure out the best way to do the task for each platform.

I've talked with developers who have released professional-calibur cross-platform apps and universally they sing the praises of REALbasic's cross-platform capabilities. Sure, they tell me there were obstacles, but in general they were minor, and just required a little dedication to figure out a solution.

On the other hand, I know many casual users who take a Mac-only app and try to compile it for Windows, and then whine when it doesn't work. While some simple apps can be compiled for the other platform with no changes whatsoever, generally that's rare. Most projects need a little tweaking to get them work. I wouldn't be afraid of it, but I wouldn't assume that REALbasic is magic and will automatically solve all platform differences for you. Creating a cross-platform app requires dedication and work. For the amateur that can be frustrating; while the professional sees it as a dream because compared to trying to write cross-platform apps in traditional languages such as C++, REALbasic makes it a breeze.

I'd compare the situation to cross-platform web development. If you've ever done any web work, you know that there are subtle and annoying differences between platforms. I just discovered two this morning on my REALbasic Developer website. For instance, I had the background of a table set to color "#FF0" instead of "#FFFF00" -- a shorthand approach that's supposed to work. On the Mac this worked fine, but under Windows this yellow showed up as black. I changed it to the longer color value and it worked fine in IE under Windows.

That's similiar to the types of problems you'll encounter using REALbasic for cross-platform development. Some of these are bugs REAL Software will fix, others are just differences between the operating systems. The frustrating part is that until you know about them, cross-platform development is more challenging than it needs to be. The good news is that every release of REALbasic gets better and better in this regard.

My final advice to you is to recommend you give it a try. You can download the 30-day demo version of REALbasic for the other platform and see how your app runs. If it's not working, try to figure out why, and keep at it for a bit. Many times what seems to be a horrible error (your app is crashing) turns out to be caused by one line of code or something trivial to fix. Trace through the program, step-by-step, and watch what it's doing. You'll find the error.

For instance, I once had a program that wouldn't work on Windows and I finally figured out I'd forgotten that my help system tries to load the file from the program's resource fork -- something not available under Windows. But because the help system was something that loaded in the background and wasn't intimately associated with the core of the program's task, it took me a while to figure out that's where the program was. I added a few lines to make it grab the help file off disk if it's running Windows and bingo, the program worked!

As I mentioned earlier I'm not proficient at cross-platform compiling. But I've just bought a Windows box and I'm preparing to learn. I realize that many RBU lessons aren't cross-platform, which is something I would like to rectify. Future lessons I'll be able to test on both platforms (and eventually Linux), and as I learn more about cross-platform issues, I'll be sure to share them with REALbasic University readers.

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

.