The App Class

Every application you create in REALbasic, whether it's a console application or a desktop application, has a special object, App, which is an instance of the App class, a subclass of the Application class. If your applications are relatively simple, the App object could very well be the only area of your application where you have to be concerned about cross-platform issues.

I call App a class, but it's really kind of a magical thing that falls somewhere between a class and an object. Like a regular class, it can be subclassed. At the same time, if you do nothing it will be implicitly instantiated every time your application runs, so you never have to do that yourself. If you subclass App, the subclass lowest in the hierarchy is the subclass that is instantiated. For instance, if you create a class MyApp that is a subclass of App, MyApp will be the version that is instantiated. In REALbasic lingo, the instantiated version is the "blessed" version of App.

After you've launched a new project in the IDE (shown in Figure 4.2), select App in the Project Editor; you will see the list of App's properties, which you can set.

Figure 4.2. The App object.

App Properties Pane

The App Properties pane also provides you opportunities to configure your application for cross-platform development. The ListBox is divided into sections, and I'll address each one individually.

The ID Section

The ID properties are the same basic ID properties that every class hasName, Interfaces, and Super. In the default App class, you can see that it does not implement any interfaces, but it does subclass the Application class. As I mentioned earlier, you can subclass App. The subclass of App that is the lowest in the hierarchy (the App subclass that's not a superclass of anything) is treated as the "blessed" version, and it is the one that is automatically instantiated. Regardless of which subclass is used, the values set in the Properties pane remain valid.

The Appearance Section

The Appearance Section sets values for windows, menus, and icons.

Default Window

This setting determines the default window that gets automatically launched when your application starts. It defaults to Window1, which is the default window that REALbasic places in each project.

MenuBar

MenuBars are discussed in much greater detail in the next chapter, but this is where the default menu bar for the application is set. MenuBars are one area where some significant differences exist between the Macintosh platform and either Windows or Linux.

Macintosh computers have only one MenuBar available at a time, and it is always at the top of the window. Contrast this with standard Windows and Linux behavior where the MenuBar is associated with each window. You can have two or more windows open, and each one can have a different MenuBar assigned. This is not the case with Macs.

By default, this value is set to MenuBar1, which is the magically instantiated MenuBar that is created whenever you create a new REALbasic project.

Icons

Applications normally have a group of icons associated with them. One is for the application itself, and potentially others are associated with files created by the application. The App object provides a simple interface for associating an icon with the applicationone that lets you avoid the details of doing this on the native platforms (all of which handle this differently).

In the App Properties pane, click Icon in the Appearance Section and the Edit Icon window will appear. On the left side is the list of Icon Variations, which list the standard sizes and the different color depths to be used for them. The largest icons are 128x128 pixels, and the smallest are 16x16 pixels. With the exception of the 128x128 pixel icon, all others come in two color depthsmillions of colors and 256 colors. When you prepare a REALbasic application for cross-compilation, you will need to have an icon for each size established. If you don't, REALbasic will use the default application icon on each platform.

To the right of the Icon Variations ListBox are three boxes, labeled Image, Mask, and Preview. In the following example, I have selected the 128x128 size icon, and I have simply cut and pasted an image I created in a graphics program. Immediately, the Preview box is filled in, refer to Figure 4.3.

Figure 4.3. Create an icon for your application.

As you can see in the previous example, the background in the Preview box is white, just like the image that was pasted into the Image box. This means that every time you see this icon, it will have a white backgroundon the desktop, in different folders, and so on. To have a transparent background, you need to use a mask.

When I created this icon, I used Canvas; it has a convenient feature that lets me automatically generate a mask for an image. Using the same graphic as the starting point, I had Canvas export the mask, which left two images that I pasted into the Icon Editor. In the Image box is an image with a white background (note that it looks a little different from the original pasted one), and in the Mask box is an image that also has a white background, but in the Previous box you can see the icon with a transparent background.

Think of it like a mask you wear for Halloween. If you put a mask on, your face is covered, but your eyes can be seen. The Mask image in the Icon Editor, the white part is the "mask" and the black part are the "holes" that you can see through. The mask is laid over the original image; the parts that are masked are transparent, and the parts that "show through" are seen, see Figure 4.4.

Figure 4.4. Make the icon background transparent.

After you have your icon properly masked, you need to cut and paste the icon into the other sizes. The following example shows the same icon in 256 colors and 48x48 size. The reason REALbasic gives you the option of creating different sizes instead of doing it automatically for you is that sometimes automatic scaling doesn't look good, especially if you use an icon with a lot of colors or complex shading patterns. To create an icon that looks good at all sizes, you may need to create distinct versions in various sizes before copying them into REALbasic as shown in Figure 4.5.

Figure 4.5. Copy and paste to create different-sized icons.

The Version Info Section

The Version Info section lets you document the particular stage of development your application is in. How you want to use it is largely up to you, but some of this data is made available to the system and accessible by the user, so you want to make sure you fill it out.

Although there is no "standard" way to version an application, some ways are more standard than others. A common practice is to use three digits separated by a period, like so:

1.2.3

The first digit is the App.MajorVersion number, the second is the App.MinorVersion number, and the last of the numbers is referred to as the App.BugNumber. MajorVersion and MinorVersion are constrained to values between 0 and 255.

In addition to these three numbers, you can also identify the App.StageCode value. There are class constants that can be used for the StageCode values (and, yes, as of RB 2005 r2, the misspelling of Development is required):

App.Developement = 0 App.Alpha = 1 App.Beta = 2 App.Final = 3

Alpha means the application is in the early stages of development; it may be unstable and is probably not suitable for daily use. A Beta version is further along and is much more stable; it is at the stage of bug fixes and is not subject to major changes prior to the final release. Final is, of course, ready for production.

Finally, there is the App.NonRelease version, which refers to the current stage of development. So, altogether, a number like this:

0.1.1.4

Means the following: A MajorVersion of 0 means that you have not released a major version. Projects that are in Alpha or Beta usually use a MajorVersion number of 0 to signify the fact. The MinorVersion is 1, which is followed by the StageCode of 1, which indicates that this is an Alpha version of your application. This happens to be the fourth version of your Alpha. When you decide you've reached the Beta stage, the App.NonRelease version will start over again at 0.

Generally speaking, incrementing the MajorVersion indicates a big change in functionality. A MinorVersion increment indicates a relatively smaller update in features, and the BugVersion represents releases that coincide with bug fixes and things like that.

ShortVersion, LongVersion, and PackageInfo are text strings used to represent the name of your application. You can have a short and long version of the name. PackageInfo is additional text that can be used however you like. On Macintosh computers, what you enter in PackageInfo is used in the Info.plist file, in the CFGetBundleInfo element.

The Windows Settings Section

Windows Settings is the first of the platform-specific properties that you can set.

WindowsAppName

Here you place your application name. All Windows applications end with a .exe extension. This tells the operating system that this is an executable file. Also of great importance is that the name of each platform's version of your app should be different. This is because the applications will be compiled in the same directory and you do not want to overwrite them.

Bear in mind that this represents the filename of your application, not what the application should be called. You can use spaces in the name, if you'd like, but in general I'd suggest using a short, simple, and to-the-point name for the file.

MDI and MDI Caption

MDI stands for Multiple-Document Interface, and this is a Windows-only feature that even the Windows design guidelines say you should avoid. As shown in Figure 4.6, an MDI application has a single containing window, and all other windows that get open in your application are constrained to live within that area.

Figure 4.6. MDI window.

The Windows development site says that the reason to avoid MDI applications is that new users find them confusing. A better reason to avoid them is the reason offered by Apple. If you are a designer working on a Macintosh computer, there's a good chance that you are going to have multiple applications open with multiple documents open. You will probably also be cutting and pasting from a document from one application into a document of another application. The MDI interface makes this awkward, at best, to doit is application oriented rather than window oriented. When you create an MDI application, you are placing limits on how your user can use the application, and that's not such a good idea.

Macintosh Settings

The Macintosh Settings area contains configuration options for both Carbon and Mach-O builds of Macintosh applications.

MacAppName

This is the name for the Carbon version of your application. You do not have to end the name with a particular extension. Any name will do (although I will talk about some constraints on filenames in the upcoming section on files).

MacOSXAppName

The OS X version of your application name will end with .app, but you do not have to enter it hereit will be done for you automatically. The name used for an OS X name differs from that used for Windows and the Carbon version because it doesn't refer to a file, even though the Macintosh user interface treats it like a file. This name points to a folder that contains folders and files related to your application, which is called a bundle in Macintosh terminology. I'll return to this later.

MacClassAppName

The name for your "Classic" Mac application. It has to be limited to 31 characters or fewer, but it can include spaces.

MacCreator

All Macintosh applications have a creator code, which is a series of four letters. These codes have to be registered with Apple to use them, and it provides a unique identifier that the system uses to identify an application and files created by that application. Although Apple seems to be moving away from this approach, you will need it to successfully build your application in REALbasic and link your application icons and files created by your application to the application itself.

AcceptFileTypes

Macintosh applications let you drag and drop a file onto the application as a method of opening the file (it can be used to do anything you want, but that's what it is most commonly used for). You can list the names of the accepted file types here. However, to do that, you need to know how to define file types, and that is discussed later in this chapter.

The Linux Settings Section

Linux settings are simple enough: the application name. Linux requires no special extensions on its applications. Because it is a UNIXlike environment, the operating system knows that it is an application if the Executable permission is set to true for either the owner, the group, or the world. File permission settings will be discussed later in this chapter.

The Advanced Section

The advanced settings are new to REALbasic. The first two allow you to determine a minimum amount of memory for your application to use, as well as a suggested amount of memory for your application to use. The general rule is that the more memory your application has available to it, the faster it will run, but there is one big caveat: You don't want to allocate so much that you use so much of your computer's memory that it has to begin relying on virtual memory, which involves saving data to a file and reading out again, which will slow down your application terribly.

I do not know of any general rule or guidelines about how best to set these values, because it depends on a lot things.

The last of the advanced options is IncludeFunctionNames, which determines whether the English (or whatever language you speak) function names you use are compiled into your application. If you select yes, others can peek and see how you've named your functions. This may or may not be interesting information to them, and you may or may not want them to have it.

In addition to the properties available in the Properties pane, the App object has a full range of events and methods as well. I will revisit the App object in the next chapter.