Creating a New Cross-Platform Application in Revolution

  Joe Wilkins       February 21, 2007      Tutorials Mac Developer

When I first started thinking about this Chapter, I lost focus and started thinking about knowing all there is to know about Revolution. That was naive, and pretty stupid of me. I had exposed myself to a little bit of the vastness of Revolution and started thinking in grander terms than my original conception, which was to provide the old HyperCard crowd a really good excuse to shift their long-standing HC devotion to Revolution by demonstrating that Revolution can be a fairly simple extension to their HyperCard addiction. That group, on a worldwide basis, was - and is - huge. This will allow them to continue solving most of the same kinds of problems they had handily tamed with HyperCard; but with added dynamism and much fewer restrictions. I am not abandoning this ambition to know all about Revolution; rather I am facing up to the fact that, as is often stated in text books on most all topics, “it is beyond the scope of this publication.”

Retreating to the same mentality I had when I first attacked HyperCard, I’m going to concentrate on creating some limited capacity stacks and then extend their behavior as stand-alones. Meaning that, even though there are a whole host of really fantastic things that can be done with Revolution, we’re just going to experience the tip of this gigantic iceberg.

So, we’re going to create a somewhat, but not too, elementary Revolution stack from scratch and then turn it into a standalone application for both the Mac OS X and Windows XP operating systems. We won’t complete those tasks completely in this Chapter. Just this past Monday, Revolution Version 2.8 was announced, which provides full Windows Vista compatibility; however, we still have a few unresolved issues from last week, things that I promised I’d find out about and announce this week.

What Can’t Be Done With the Media Edition of Revolution?

You can’t convert HyperCard stacks to Revolution stacks. That takes the Studio Edition.

You also cannot create standalone applications for any platform.

You can create fully functioning Revolution stacks, using all of Revolution’s features; but if you plan to distribute them to others, they will also need to have the Revolution Player, something that is free and may be distributed with your stack creations. This is something that was also done with HyperCard when it finally introduced its ability to produce standalone applications.

I am told that the Revolution website is making all of this much clearer to those who come to take a peek. I also indicated that I would make some other issues a bit clearer.

HyperCard Backgrounds versus Revolution Groups

Most importantly, how do we create the equivalent of the HyperCard background? The HC background is a “layer” between the cards of a stack and the stack itself. It’s like the scenery for the activities that take place in a stage play’s “scenes.” When a play’s scene changes, a break occurs during which time the stage hands come out, usually while things are dark, and rearrange or change the props used and maybe even place a new backdrop for the next “set.”

All of the activities that take place while that scenery is in place is very much akin to what happens on the cards of a HC Stack that have the same background. Buttons, fields and graphics occurring on a card with a specific background are shared by all of the cards with that same background. With HC, all cards created while “in” some background, have that background as “their” background. Even though a field is shared amongst a number of cards, the contents of that field do not necessarily have to be the same on every one of the cards, but if it is NOT shared then it will or may be different on all of them. There are other subtle nuances as well.

The following is a step-by-step process for creating/using “Groups” with Revolution. Once created, they function much like HC’s backgrounds; though, as mentioned, there may be multiple “Groups” resident on any card. I still don’t feel comfortable using them; and, recently, I messed up a stack I was developing to the point of having to revert to one I had saved nearly 10 days earlier. I won’t wait that long between making backup copies again. My only consolation was that when I redid all that I had done in the interim I did it much better. I probably would not have started over without the loss I’d faced. Sometimes good things come of bad things! At least I’m able to see it that way.

Creating/Using Groups with Revolution

1. Create any object or objects. Select them by lassoing them, or shift/clicking them one-by-one.
2. With the object(s) selected, choose “Group” or “Group Selected” from the “Object” menu or the ToolBar at the top of the screen.
3. Open the Grouped Objects’ Property Inspector.
4. Check the “Behave as Background” checkbox or set the backgroundBehavior to true using the Message Box.
5. If there are existing cards, you must go to each one and choose “Place Group” from the Object Menu; new cards created from a card that has the Group already in place will automatically have all of the objects in the Group.
6. Instead of going to each existing card, particularly with a large number of cards, write a script to accomplish the above actions; you may skip cards you don’t wish to share the groups object(s).
7. Be careful if you want to add more objects to the Group. It is not as simple as just selecting an existing group along with some other object or objects and doing a Re-Group, as I feel it should be; unless I’ve missed something, you must ungroup the existing group, which may make it appear that you’ve lost everything, particularly if you already have more than one card. The newly “un-grouped” objects will appear on the card on which you performed the “un-grouping.” The other cards will have no objects from the group. When you create a new group with the added objects, you will have to treat all of the cards as existing when that group is created; meaning you must go to each card and “place that group” on it. The upshot of all this is that you should plan carefully ahead to make sure that your design is complete before you start creating any more cards. Otherwise, it can be quite confusing and frustrating. I’m sure this topic will be addressed again; and, perhaps, again.

A New Revolution Stack

Even though I have discussed Groups at length, the new stack I will now create will have but a single Group, that one for the menu bar; mostly because I began this stack prior to having any real understanding of Groups and what they might be used to do.

As mentioned last week, this stack will be an Activities and Coloring Book pertaining to the places and things that actually happen in the City of San Diego, California. In concert, two lady friends of mine prepared all of the visual and textual data that is to be displayed in this computer book. They did this originally in the form of an actual printed book.

When they decided they wanted to have a computer version of the book, they scanned their original artwork and took pictures of various places, since the computer version was going to do a lot more than their printed book. I had built a prior computer version using FutureBasic3 for the Mac. This entailed the creation of a complete program that displayed all of their artwork, photographs and text in a HyperCard-type application, but it ran only on Macintosh. These ladies also wanted it to run on WinTel machines. As I had done on five prior occasions, I could have dusted off Virtual PC along with Visual Basic and have furnished the WinTel version accomplished totally with my Macs; but, then, Apple did a switcheroo and, suddenly, we were also going to want a Mac OS X universal binary version. To complicate things even further, Microsoft finally announced that the new Vista OS would be available in 2007.

Then I happened across the fact that Revolution was now universal binary capable for the Mac and would soon be Vista enabled for WinTel machines. This was all just too good to be true; and Revolution’s scripting language, Transcript, was an extension of my favorite HyperCard language, HyperTalk. What with my philosophy of Learn by Teaching, I announced that I would start writing a series of articles about Revolution on Macinstruct; intending all along to complete this cross platform application for the “San Diego Activities and Coloring Book” in the course of writing the articles. I have all the data I need, I just need to build a skeleton into which I can plug all of it.

I opened Revolution 2.74 at the time, but soon to be 2.8 for Vista compatibility; selected File>New Mainstack and waited a second or two for it to appear on the screen. Since I had already programmed the application using FutureBasic3, I knew exactly what menus I wanted to use, and also knew by this time that it would be a good idea to create them before I did anything else, since they would be a “Group.” I opened the stack’s inspector and set the stack size so that it would fill the entire screen. After having read Dan Shafer’s book Revolution: Software at the Speed of Thought, and some experimentation while writing the Introductory Chapters of the Code Mojo column, I was aware of some of the problems that might arise due to the different placement of menus in the two target operating systems.

So I selected Tools>Menu Builder and the following dialog appeared immediately. You won’t see the virgin dialog that I saw, because I’ve already created the menus I’m going to use, I chose not to set the “Set as Menu Bar on Mac OS” checkbox at this time, since I’ve found things work out better if you lay out your cards with the Windows menus occupying the upper left corner of the cards. Once again I’m not going to step through all of the aspects of creating menus, mostly because it really is “Easier Done than Said™”. But I will say a few things that may be somewhat puzzling to a newbie.

As you may notice, “Mnemonic” is Checked and the letter “F” is chosen from the small popup menu to its right; then looking at the File Menu you will see the letter “F” is underlined. On a WinTel machine this allows the user to press Control/F and the File Menu will open up as if it had been clicked upon, a feature that Macs do not posses.

Above you can see the menus for the Book as they will appear on a Windows machine. I’ve used most of the traditional HyperCard navigation command keys, and the Color Menu supplements a scrolling field that provides a method for the user to select any one of the 552 different colors made available through Revolution. It only appears on the cards with pictures intended to be colored. The Music menu is kind of neat, because the user may play the provided music or may replace them with tunes of their own. Once started, a piece continues to play even if the user switches to something else on their computer, like working with their email. The About Music item tells them exactly how to make this work.

Above see a partial screen shot of a ResEdit Resource file of PICTs.

After creating the Menus, and implementing the various menus with scripting that does what might be expected, I then created a total of 56 additional cards. Then came the interesting part. I opened ResEdit and inserted copies of all the scanned artwork and photographs provided by my lady friends. So as to not forget, I copied the resource that I had used for the About Coloring Book® menu item and pasted it into a new sub-stack I had created by selecting File>New Substack of San Diego Activities. While it was active I opened its Stack script and placed an on mouseup handler in it that just said “Close me.” Then I found that clicking on the Main stack while this Substack was open merely put it behind the main stack rather than closing it; I then discovered that there is a property that can be set for a stack that keeps it in front of anything else. Checking this solved that problem. Now when I click outside the About stack nothing happens. I had to click directly on the About stack to close it. Below is the completed About Coloring Book® substack.

The last problem was how to show this About substack. Since I had failed to open the Help Menu that had been auto scripted when I created it, I was unaware that the last item is “About the name of the stack”; in this case “About Coloring Book.” So I asked this question of the RevList and within the hour I was directed to the Help Menu item. Just putting “Open stack “About Coloring Book®” into the Help menu’s switch/case statement solved this last issue.

Since I had the graphics for each page in the ResEdit Resource files in the correct order, I just traveled back and forth between ResEdit and Revolution, copying and pasting one picture after another. I had sized the stack so that it covered my entire screen. The pictures varied in size a bit, but as I pasted them into a Revolution card they looked somewhat like the following:

If a picture didn’t appear exactly where I wanted it, I could either drag it to a new location, or move it with the arrow keys a pixel at a time when I needed to be very precise. Without trying to put the pictures anywhere in particular, they would paste into the exact center of the cards, taking into consideration their size. Not all of the pictures were exactly the same size. By using the handles around the pictures I could even make minor adjustments to the picture sizes, though too much adjustment started to distort the images. The following picture was the first one, serving as the opening screen for the Coloring Book.

This is an index of the Activities and Coloring pages in the “book.” One of the first things I did was place transparent buttons over each line, into which I placed a script handler that takes the user to the card for that topic. Example: go cd 3 for the first one that took the user to the following card.

The scrolling field at right displays all 552 colors that may be used with their names appearing in their colors. Slightly faint, but generally discernible. Clicking on any Color Name sets the current BrushColor to that color and changes the cursor to the Paint Bucket Tool. Then a click anywhere on the page fills that area with that color. Instead of an undo, the button in the lower right corner chooses the paint bucket tool and sets the painting (brush) color to white. Clicking on an area previously colored changes it back to white once again. This works quite well and even works after the book has been colored and closed. The Color Menu you saw earlier may be used to select some of the most basic colors, the Coloring Instructions and changing of tools.

This scrolling field only appears on about half of the cards, so it was not grouped, but along with the button below it, copied and pasted into each of the appropriate cards. Since the cards were all created before it was decided to use this method of selecting colors, the field and button could have been grouped and then only placed on the cards where desired. Were this done, it would have been just as time consuming and would have eliminated the possibility of modifying its location, even a little bit, on each of the cards.

The following are a couple of the other cards showing them in partially colored state. All of the pages of the book may be printed with a simple Transcript handler in the File Menu that essentially says “Print this cd.”

This card is one of three showing a map of the San Diego area with various places of interest shown with a red star. Clicking on the stars reveals a photo of that “place” along with a voice reading the photo’s description. Clicking on the picture, pressing the enter key or going to another card closes the picture.

This card is a collage showing several celebrities who have stayed at the Hotel Del Coronado over the years. Clicking on the balloons illicits a short monologue quotation from that individual.

There’s not a lot more that needs to be done before we save this Revolution Stack as a standalone application, but this is longer than I had anticipated, so we’ll save the balance of the job for next week. The scripting for this stack has been pretty minimal. Mostly a matter of navigating through the various cards. There are a couple of the cards, such as a crossword puzzle page, that will prove to be a bit more of a challenge. We’ll face that next week.

Don’t forget to write if you want to know anything about what I’ve done. The important part is to remember how easy all of this was to do.