Sunday, April 29, 2007

Porting Model Railroading Software to OS X From Windows

Last week, TrainPlayer International released a Mac OS X version of Train Player, their application for designing model railroads. I had something to do with this. I setup the general structure of the application at the start of the porting project, implemented a number of features, and worked into the debugging stage. But my real job has been nothing but debugging for the last two months, and I have nothing left to give to side projects, so they've had to get along without me.

This blog entry is the first of two on the project. This will cover GUI differences between a Windows application and a Mac OS X application, in terms of user expectations. The second will be on designing an application under the hood to share code between a Cocoa application and an old MFC application.

What Mac Users Want

The first thing I noticed about the interface was the surfeit of toolbars. With buttons for nearly every action.

When I worked in Illinois, we called this "Marketing Mode." Compare this with the left

and the right side of Apple's Pages word processor.

Apple Pittsburgh spent untold hours categorizing the actions required to lay out text, and distilled them into six icons. I can imagine the pressure they felt to add a special button here or there for someone's pet function. "What about a spell check button?" But it is important that toolbar icons be few and large in order that mouse acquisition times be short, requiring thoughtful selection of buttons. Notice there is plenty of room under the large icons for actual descriptive words; sometimes a word is worth a thousand pictures.

The second thing I noted was how often the user was required to open a modal dialog box, sometimes two, or even three nested modal dialogs to configure some user interface element. For example, to change the labels for a series of railway cars you would select a car, choose "Properties..." from the "Train" menu, to bring up this modal dialog:

which you would modify, hit "OK" and repeat for every car in the series. Modal dialogs are great for programmers; work flow is linear and controlled. If the user hits "Cancel" you just don't change your data structures, while if they hit "OK" nobody expects you to allow them to undo it; you've already given them a chance to back out. It's just so easy. But, Mac users these days are used to more.

The more they expect is a modeless, floating inspector window.

This allows the user to select, change and rapidly select and change again, all without losing focus on the document. It should allow for undoing changes (although apparently that functionality hasn't been added yet to Train Player, but should). The user should feel more comfortable and able to work in a more free flowing manner.

The Windows version used GDI graphics for its rendering needs, resulting in pixelated track paths like this:

I felt OS X's Quartz graphics environment would create much cleaner lines if we treated tracks as continuous paths instead of discrete segments and the Windows programmer was willing to make the changes needed to get nice anti-aliased and beautifully joined paths like these:

Similar effects could be achieved under Windows with GDI+, but I felt the typical Mac user would immediately see what was missing and demand higher quality. Quartz also allows any object to cast a shadow, making this effect: extremely easy to produce. Simple as it is, this translucent shadow makes the cars pop out and resulting in a more realistic look.

Along the same vein, Windows users see this clock:

while Mac users will see this clock with a composited reflective crystal and hands throwing shadows:


The Windows version had a modal dialog to choose individual cars from collections. It had two modes: an icon view and a table view, with each collection selectable via a tab.

I felt there was no need for two modes as the Mac table class was capable of displaying the larger image; and I am leery of using tabs to represent categories, especially when the user could install or create their own. Therefore, I replaced the tabs with a single column table as you might see in an iLife application, and I merged the two modes into a single table grid.


In other areas, I left it up to the experts at TrainPlayer, they know model railroading, whereas I only know generic applications. So when they say this is how you build up a set of tracks, this is how you build a set of tracks:

And this is how you run a simulation on a completed railroad:

I wish YouTube didn't add an ugly filter to its videos. You have to see how pretty it is.

What Was Achieved

In many ways, I'm proud of the result so far, and I expect the application to go through a rapid process of refinement now that it is available to a wider Mac user audience. Areas of the GUI where I varied it from the Windows original are definite improvements, some of which could be back ported to give the Windows user base a taste of Mac refinement.

In other places, I'm not thrilled. After I left the project, too many buttons crept into the GUI, and text fields really should support undo. Today's standards are high, it's hard to keep up, especially while reusing large chunks of C++ code, and bitmap images from a Windows application. The good thing is there is always version 1.0.1.

Porting is a balancing act. You've got to know what code and what GUI elements can be reused, and which must be re-implemented in order to avoid the dreaded "Looks like a Windows port" review. I think we've avoided that, and that's an accomplishment in itself.