REALbasic Cross-Platform Application Development

The desktop metaphor has taken over the world. You'll find it everywhere you lookon Macintosh (which popularized the notion), Windows, and Linux. Much like high school students, who all want to dress like their friends but each in their own special way, computer operating system designers want to create operating systems that are familiar to users of other platforms. That's probably a good thing, even if a little lacking in imagination. At the same time, there's only so far they're willing to go with this, so here and there they also insert little improvements, modifications, or allegedly better ways of doing things.

For example, Macintosh and Linux have trash, whereas Microsoft has a Recycle Bin. (From time to time Mac aficionados accuse Microsoft of recycling Apple's innovations, so the name may be appropriate.)

Each platform has a way of navigating through folders. It's the software that lets you drag files around, copy them, put them in the trash, and double-click them to open them up. They all use different names.

For Macs, it's the Finder, and for Windows it's Windows Explorer. There is more than one competing system for Linuxthe two leading ones are Konqueror (KDE) and Nautilus (Gnome).

Desktops

The following figures show a sample of each desktop. Another one of those things that they all do, but in a different way is the taskbar/dock/pane thing, which is usually something across the bottom of the screen (by default) that provides easy access to programs you use often, among other things. On Windows, it's called the taskbar. An example of the Windows desktop is shown in Figure 4.12. On the left side of the taskbar is the Start menu, which is where you can launch applications, and at the far right is the notification area. At a minimum, you're notified of what time it is.

The Macintosh desktop (see Figure 4.13) has a MenuBar across the top, giving users access to Finder functions, and it has a taskbar-like Dock across the bottom. The AppleMenu on the far left of the MenuBar contains options for setting preferences, shutting down applications, and switching users. To the far right is the time display. Volumes are mounted directly on the desktop, unlike Windows.

The Linux desktop (see Figure 4.14) is an interesting hybrid of the two, although definitely more Windows-like than Macintosh-like. KDE and Gnome are similar, but different enough that you would need to look at each one to do anything special.

Because the Linux build is relatively new, REALbasic has fewer Linux-specific classes than it does for Windows and Macintosh. As you'll see in the next sections, REALbasic does provide limited access to the Windows taskbar and the Macintosh Dock. I'll show you a few brief examples of how to use them.

Windows: Taskbar

The Windows Task bar is shown in Figure 4.15.

• Start menuThis is where the user starts applications, accesses the Control Panel, logs in and out, and shuts down the computer.

• Quick Launch toolbarIcons that allow applications to be launched with a single click are in this location. This is user customizable.

• Taskbar buttonsThere is a button for each window that is open without a parent, which means that there is a button for each open application and document window (but not for things like alert boxes and other related windows). If there is not enough room to show all the open windows, the taskbar groups open windows by type.

• Status (Notification) areaApplications can put icons in the status area to notify the user about events or other important information. The actual functionality of these buttons isn't regulated, so there is not much in the way of standard behavior. This area also displays the current date and time.

TrayItem Class

The TrayItem class is not a control, per se, but it is often treated like one. Controls and control-like classes will be discussed in full in the next chapter. In the meantime, just know that a TrayItem shows up in the notification area. You can assign a TrayItem an icon, and the user can click or double-click that icon and your application will respond accordingly.

Macintosh: Dock

The Dock plays a similar role that the taskbar does for Windows, but with some important differences.

The Dock does not have the equivalent of a Start menu. Instead, the menu bar at the top of the screen (and available with every application, unless hidden) has a menu item designated with an image of an Apple (called the Apple menu, of course). Here the user can access systemwide preferences, stop and restart applications, force quit hung applications, and related tasks. The clock is also available on the menu bar, at the far right edge, which is also where the user can search the hard drive.

The Dock itself is customizable. It combines the functionality of the Quick Launch toolbar and the taskbar. The user can drag applications and files onto the Dock, where they will stay, and which can be launched or opened by clicking them. A black arrow is shown for every open application, in contrast to creating a button in a different part of the screen, as is done with the Windows taskbar.

A DockItem object is available in two locations while your application runsthe App object and any window:

App.DockItem as DockItem Window.DockItem as DockItem

The DockItem object has one property, which is a graphic that represents the icon that appears in the dock:

Dockitem.Graphics as Graphic

Two methods allow you to reset the icon to the original form, or to update the icon immediately:

Dockitem.ResetIcon Dockitem.UpdateNow

The Graphics class may be new to you, but one of the features it provides is being able to automatically draw certain items onto an existing graphic. This example leverages that capability and draws a Stop icon on the application icon that appears in the Dock. See Figure 4.16 for an example of the output before the icon is drawn; Figure 4.17 shows an example of what it looks like after it's drawn.

#If TargetMacOS Then Dim di as DockItem di = app.DockItem di.Graphics.DrawStopIcon(15,16) di.UpdateNow #Endif

As you can see, it's very easy to do. Usually, the icon in the Dock is supposed to convey some kind of meaningful information. For example, the Mail application that comes as a default on OS X places a red oval circle in the upper-right corner of the icon that shows how many new mail messages you have.

Linux: Pane (KDE and Gnome)

The Linux environments use an approach that is closer to Windows than the Macintosh Dock. Both KDE and Gnome use different approaches to the Pane, and at the time of this writing, REALbasic did not provide any special classes to manipulate the Pane.

Keyboard

The Keyboard object is used to test to see if certain keys are being held down. The keys in question are usually used in combination with another key to interact in some special way with the application. Menu shortcuts are a prime example; on a Macintosh you can quit an application by holding down the Command and Q keys at the same time. On a Windows PC, you hold down the Control and X keys to accomplish the same thing.

The following table identifies some common tasks and the keys used to accomplish them on the different platforms.

Linux has keyboard shortcuts, as well, but there isn't the same level of standardization, and many of them apply to the console rather than GUI apps. Generally speaking, Linux tends to mirror Windows so you can use that as a guide.

By default, Macintosh computer mice have only one button. To emulate a two-button mouse, the user holds down the Control key while clicking the mouse.

The Keyboard object has the following properties, which enable you to test to see which keys are being pressed. There are two versions for each keya regular one and an asynchronous one. The asynchronous property is used to find out what key is being held down at that particular moment, and it is usually called from a Timer. The other version tests to see whether the key was being held down when the current method or event handler was called.

Keyboard.AltKey as Boolean Keyboard.AsyncAltKey as Boolean Keyboard.ControlKey as Boolean Keyboard.AsyncControlKey as Boolean Keyboard.ShiftKey as Boolean Keyboard.AsyncShiftKey as Boolean Keyboard.MenuShortcutKey as Boolean Keyboard.AsyncMenuShortcutKey as Boolean Keyboard.AlternateMenuShortCutKey as Boolean Keyboard.AsyncAlternateMenuShortCutKey as Boolean Keyboard.OSKey as Boolean Keyboard.AsyncOSKey as Boolean

Because the platforms use different names for what is effectively the same key (Macintosh calls it Option, whereas Windows calls it Alt), REALbasic refers only to a generic name for the key (which is the name used by Windows). The following table shows the equivalent keys on a Macintosh.

At one time, REALbasic had properties for Macintosh-specific Command and Option keys, but as of REALbasic 2005, those properties have been deprecated.

The Keyboard object also has two methods for you to use. The first provides a generic way to test whether a particular key code is being pressed. However, you have to know the key code for the particular key you are interested in, which is no small task because it seems to vary quite a lot in some circumstances.

Keyboard.AsyncKeyDown(aKeyCode as Integer) as Boolean

There are some keys that have been given a name, such as the Escape key or the Shift key. The Keyname() method provides a way of getting the name of a key associated with a particular key code. If the key code passed is not a named key, the letter associated with the key is returned. Note that in the early releases of REALbasic 2005, there was a bug in this method that caused a rather nasty crash in certain circumstances.

Keyboard.Keyname(aKeyCode as Integer) as String

If you check REALbasic's documentation and dig around on the web, you'll find charts that map key codes to letters according to REALbasic. Each one I found is a little different, and it depends on the keyboard being used.

Menu Bar

Macintosh computers have one menu bar that stays positioned at the top of the screen at all times. Windows and most Linux distributions (as well as Java applications) associate a menu bar with each window. REALbasic shields you from most of those differences, but it's good to be aware of. The specifics of how to create MenuItems in REALbasic is covered in the next chapter, but there are a few things you should be aware of.

I've already written about key modifiers, but Windows has another concept called keyboard accelerators, which is how users interact with the Windows menu entirely through the use of the keyboard.

If you look at the constants in the App object, you'll see the following values:

kEditClear = &Delete kFileQuit = &Exit

These constants are used to determine the names of MenuItems. When the application is running, the letters that follow the ampersand (&) are underlined. The standard File MenuItem looks like this:

File

The user can activate this on Windows by pressing Alt+F. The MenuItem opens up and all the options have one character underlined as well (each unique, of course). Continue to select MenuItems by the pressing the Alt key and the underlined letter to navigate through the menu.

Even though Macintosh does not have the same concept, you will need to make provisions for this if your application will be running on Windows. It's an important part of the way that Windows is made accessible to people with disabilities, so it's not something to ignore.

REALbasic provides you with views of how the menu will look on all three platforms. Macintosh computers also have some special MenuItems, and they are given special classes to handle them:

PrefsMenuItem Class

On Macintosh OS X, the Preferences MenuItem is under the Application Menu, which doesn't exist for Windows and Linux systems. Place the item in the menu where you want it to appear on Windows and Linux, but make it a subclass of the PrefsMenuItem class so that it will appear in the proper location when compiled for an OS X computer.

AppleMenuItem

The AppleMenuItem applies only to "Classic" Macs. You use it the same way as the PrefsMenuItem class except that instead of showing up in the Application MenuItem, the new MenuItem will show up under the Apple MenuItem.

Screen

The presence of the Dock, the taskbar and the Pane have an impact on how much of the user's screen space is available to your application. REALbasic provides a generic means of managing this issue with the Screen class, and the related Screen() and ScreenCount() functions.

You never access the Screen class directly; you always use the two functions to access it.

The ScreenCount() function returns the number of screens the user is using. Most of us use one, but there are many situations when a person may have two or more monitors in use. One common example is when you have a projector attached to your laptopthe laptop monitor represents one screen (screen 0) and the projector represents the other (screen 1).

After you know how many screens are available and which one you want to access, you then turn to the Screen() function, passing an index position to it, as in the following example:

Dim aScreen as Screen aScreen = Screen(0)

After you have a reference to the Screen instance that interests you, the following properties will be accessible.

Depth refers to the color depth of the screen:

Screen.Depth as Integer

Height and width measure the absolute height and width of the screen in pixels:

Screen.Height as Integer Screen.Width as Integer

Top and Left refer to the position of the current screen relative to the main screen:

Screen.Top as Integer Screen.Left as Integer

Top and Left are applicable when more than one screen is available. When you place the position of a window in your application, the coordinates are measured in terms of the main screen, and this allows you to control where your window is viewed.

The "Available" properties refer to the screen space that is left over after you take into consideration the Dock, taskbar, or Pane:

Screen.AvailableTop as Integer Screen.AvailableLeft as Integer Screen.AvailableHeight as Integer Screen.AvailableWidth as Integer

On Macintosh in particular, the available screen space can be significantly smaller than the overall screen space. You should always check the available screen space if there is any chance that the window will be larger than the available space.