Object Master 2.5 Universal

A slightly dazzled review

By Andy Dent, A.D. Software, Ballajura, Western Australia

About the Author

Andy Dent - Andy comes to us from the ranks of the former Software Frameworks Association (SFA), and has enjoyed using Object Master to help himself master new big chunks of object oriented code, like PowerPlant. You can reach Andy on the Internet: dent@iinet.com.au, or on CompuServe: 100033,3241, A.D. Software

I tend to develop a love-hate relationship with ACI products, and Object Master is no exception. Maybe it’s a French culture clash with my British origin. Object Master has a few petty flaws that annoyed me to the “up all night to teach this sucker a lesson” level. Redeeming itself, Object Master is also full of features that elicited ooh’s and aah’s when I demonstrated it to a friend. I spent 10 minutes with the OM demo on the CodeWarrior CD and was hooked. I hope I can show you why.

Perspective

Immediate apologies to MPW mavens and MacApp-ites. I’m neither and so I can’t fully evaluate those features of Object Master. What I’d like to do is show anyone just how much time Object Master can save you in learning class libraries and developing within complex frameworks. I haven’t been this excited about an OOP tool since I first saw the SmallTalk/V object browser. That may be because I’m trying to learn two different frameworks (zApp and PowerPlant) at the same time, neither of which comes with an object browser.

Note: in the rest of the article I’ll follow the Object Master convention of using the words method (C++ member function) and field (C++ data member). This terminology seems to be also used by most OOF (OO Folks) when discussing language-independent issues. In the interests of brevity, I’ll also use the abbreviation OM for Object Master.

Reasons to rush out and buy Object Master

OM is a tool to let you browse and manage both OOP and non-OOP code written in C, C++, Pascal and Modula-2. OM drives your compilers and linkers directly, removing the need to use the compiler IDE. It will save you a massive amount of time managing code in a complex framework, and especially learning a new framework:

• The SmallTalk-like Browser lets you edit classes and methods in a very point-and-click environment, focusing on just what you’re changing.

• The tree browser lets you display both methods and fields for any or all classes.

• The tree browser can be truncated to show you just a part of the tree, and you can turn off the Multiple Inheritance lines (useful for the PowerPlant forest).

• You can have a number of different tree and class browsers visible at once, showing you portions of the classes in varying detail.

• Subclass definitions can be generated with all the methods automatically generated for you to fill in, and override.

• C++ users can view classes from the viewpoint of different access methods. (eg: what fields do you see as a Friend class?)

• The editor provides syntax highlighting, including choice of style and color.

• An MS-Word style of line selection with a “backwards arrow” at the start of the line lets you avoid tendonitis-inducing triple-clicks.

• Think Reference is fully integrated to lookup definitions.

• MPW 411 files can be generated so you can keep your documentation in parallel with your source. (For the ignorant, whose ranks I recently departed, 411 files are indexed text files used for documentation, like an MPW Think Reference.)

• Function calls can be automatically completed, and the case corrected, from your own declarations, Think Reference or MPW 411 documents.

• SourceServer and Projector are fully supported, plus arbitrary read-locking of files.

• If you produce .SYM files (MPW and CodeWarrior) you can browse disassembled code in parallel with your source.

• Remote compilation is supported via ARA, using MPW ToolServer. (I know one user who swears by this, for working from home.)

• Resources compiled into a project can be browsed and ResEdit launched with direct selection of the resource.

• You can script in either MPW or AppleScript.

• Macro facilities provide a “fill-in-the-blanks” method for tabbing through complex declarations and common idioms. If you are heavily into patterns and idioms, this could be a great time-saver (or help those laboring under corporate style-guides).

Getting Started and the Project Environment

Where’s the “I’m Stuck!” Documentation?

I’ve seen a couple of people very strongly criticize OM in the MacDev forum on CompuServe. After running into problems with my initial PowerPlant parsing, I can understand why. The Reference Manual is generally very good, but it lacks a companion Getting Started piece. I spent a few painful hours deducing the following simple facts:

• CodeWarrior integration is not complete (who’s at fault?)

• If you get syntax errors at the end of a file, it’s almost certainly some weird compiler-specific construct earlier in the file and you can probably fix it by defining a Null or Identity Macro.

• The AppleScript menu at the end of the menu bar isn’t documented because it’s added by the scripts in the Startup Folder.

• If a Think Pascal tree is flat and you can’t see fields or class definitions, you have an interface file which is saved as a Think document, not as text.

Project Management

The OM environment is project-based. You can create a project directly from existing compiler projects, from defaults supplied with OM, from your own stationery, or from scratch. A project includes settings such as the macro definitions used to parse C++ files, and style settings for the various editing windows.

I’d like to put in a cheer for one of my favorite prejudices here - ACI has made good use of Balloon Help to assist in learning the complex menu structure and the occasional iconic buttons. Balloons are also used to describe the short-cut clicks that can be used in various scrolling list panes.

As you work in the different Project windows, you will often make use of secondary menu bars within the windows. This is an optional violation of the Apple Human Interface Guidelines. There is a Preferences setting to place these menus at the end of the main menu, but you would need a two-page monitor to see them! I found the secondary menus usable, although a little slower than a quick mouse to the top of the screen. In contrast to MS Windows packages I’ve used, the secondary menus are more comprehensible and hence faster than some vast array of iconic buttons.

Think Pascal Project Support

Creating a project direct from a Think Pascal project is very straightforward, but it may not work! The manual neglects to inform you that OM doesn’t understand the Think document format. This is compounded by OM’s failure to warn you that it has not been able to find the expected text file. OM deduces the class names from the implementation files, but you need to save a copy of TCL.p as text before you can see a proper class tree hierarchy, or any class definitions. Assuming your Pascal project has been built, the resources will be visible in OM, through a Resource Map window.

Think C Project Support

The addition of external support in Symantec C++ for Mac v6 allowed OM to directly drive the Think compilers in building projects. Loading from a project seems to work but neglects to load the resource file - you have to add that manually with the Add Files dialog. I loaded the complete TCL 1.1.3 tree and a sample Marksman-generated TCL application with no complaints. If you are only using the Think C+Objects compiler, you can set this preference in OM to speed the parsing process.

Figure 1. Project Status window
after loading the Marksman TCL project.

The Class Browser

If you’ve used a Smalltalk browser such as SmallTalk/V, or the 4D Insider tool, then the Browser window is familiar. The three scrolling lists across the top (or down the left-hand side) list the Classes, Methods of the current Class, and Fields of the Current class. The editing area contains either a single Method or Class definition.

OM allows you to have a number of Browser windows open at once, showing different aspects of the class hierarchy and with different settings (such as showing inherited Methods or Fields). The Browser is the first window in which you’ll encounter OM’s secondary menu bars.

C++ template classes are shown with a trailing Ý symbol on the class and method names. Multiply-inherited classes are shown with a trailing ° symbol on the class name. Global functions and structures are gathered into pseudo-classes and prefixed with a • symbol. (This is how you can use OM to browse a completely non-oop program.)

Figure 2. Object Browser with Show Inherited Methods
and the parent implementation CObject::Copy selected.

Editing bit-by-bit

One major benefit of using a Class Browser is focusing on the class definition or method implementation that you are writing. The OM Browser lets you very quickly navigate to the method or a parent class’s implementation (using the Show Inherited Methods option). Figure 2 shows how I’ve been able to go directly to the Copy method implemented by a parent class, looking at CArray’s methods. The “middle” pane that stretches across the center of the browser is a context feedback. When you click on a method name it shows the full signature. When you click on a class you see the inheritance path, including multiple parents (the pane is resizable). Notice the highlighting around the methods list - the panes of the browser are all keyboard-navigable, using command-Tab to switch panes.

If you are jumping between several methods, and lack the screen space for multiple browser windows, you can use a popup menu, on the bottom of the browser window, to recall any of the last ten methods edited.

Figure 3. New Class Dialog.

Creating Classes with point-and-click

I’ve always hated the messy business of defining classes that are almost-but-not-entirely-like another class, maybe overriding a couple of parent methods and adding a field or two. The New Class command in the Browser Filing menu simplifies this task enormously. You can either define a straight subclass of the current class, or a “sister” class. For a sister class, the Same as Sister button quickly marks all the methods you need to override to be just like the sister class. You can then mark a few more Methods, or un-mark some to leave them to the parent implementation. The choice of filing is flexible and makes it easy to accumulate a number of small classes in the one file.

Following Relationships

When you are trying to learn a class framework, as opposed to adding to it, you can spend an inordinate amount of time yo-yoing up and down the class hierarchy, wondering who implements a method, who calls it and how many classes further down the hierarchy override the method.

The Methods menu has an option to display the inherited methods of the current class. You can also create list windoids of classes that:

• implement the current method (same name, possibly unrelated);

• override the current method;

• call the current method (a text search that includes comments).

Understanding C++ Access Control

In moving from Object Pascal to Think C+Objects to C++, I’ve often been confused over when and how to use Friend classes (and, to a lesser extent, the other access control levels). The OM Browser allows you change the methods and fields displayed to simulate what would be available from a different Access Level. Normally, when editing, you can see everything (as an Implementor) but you can change this to restrict the list to those available to a Friend or a Client class (only the public methods and fields.)

As a short-cut, when you are editing a method (X), you can click on a different class name and choose the Class Access option See Class from Open Method. OM uses its knowledge of the relationship between the classes to display only the fields and methods visible to method X. This can be a great help at those times when you are getting compiler errors related to class access, but can’t quite understand why.

Segments by menu

The Methods menu allows you to display the Segment of Method. You can also change this from the Browser by choosing Filing - Set Method Segment. This invokes a dialog with a popup list of the current segments, and the option to type in a new segment name. OK’ing the dialog will insert #pragma directives where appropriate. For more comprehensive changes over segments, a Segment Map window allows you to drag many methods at once, to a new segment.

The Tree Browser

I was always a big fan of the Think environment’s class tree browser, but used to take up most of a monitor displaying it and flipping between classes at opposite ends of the tree. The multiple tree browsers allowed in OM and the pruning capabilities are a great time saver, by comparison.

Figure 4. Partial Class Tree, with some Methods and Fields.

Displaying Fields and Methods

Class Trees are a great way to display the inheritance path. When documenting or tracing a class hierarchy, sometimes you want to see what’s implemented by a given class. Figure 4 shows a partial Class Tree with the methods and fields displayed on three of the classes. The underlined methods are the virtual methods.

We’ve already seen the Browser allows you to display inherited fields and methods. The Class Tree nodes can popup either just the methods of the selected class, or you can turn on Add Inherited Members. Figure 5 shows how this gives you a (sometimes massive) menu with class names included and bolding used to highlight classes of the current node.

Figure 5. Popup menu of Methods, showing Inherited Methods

Focusing on Parts of the Tree

Figure 4 was produced by a couple of steps, starting with clicking on CDialogDirector and choosing Focus on Class. This reduced the class tree to just the parents of that class, and its sister classes at the same level on the tree. To complete the diagram, I then expanded CClipboard and CDialogDirector in one go, with the Expand All Classes command. Unlike the other figures, Figure 4 is not a screen shot but is produced directly as a PICT file with the Tree menu’s Save as Pict command. This could be a boon to documentors.

A faster way of producing Figure 4 would have been to click on CDirectorOwner and choose Zoom in Descendants. This reduces the tree to the sub-tree starting at the selected class. Finally, as described below, the User Class attribute can be assigned to any class and the tree reduced to just User Classes and their parents. In common use, you would use User Class to mark your classes as distinct from the MacApp or TCL hierarchy. One major disappointment for me was the Color menu. Assigning colors to classes allows you to sort by color in a Browser window. It would be very nice if the Class window allowed you to prune the tree to just the Blue classes. You could then mark several frameworks in different colors.

Multiple Inheritance

Multiple Inheritance is supported very cleanly in the class tree windows with lines drawn from all the parent classes. This can become very messy, in a dense forest such as PowerPlant, so the Single Inheritance command is very useful. It suppresses the lines from the additional parent classes. One minor disappointment was that the Focus on Class command only shows the direct parent classes. This would be a lot more useful if it also pulled in the additional parent classes. One way around this, if you want to show a partial tree with the MI parents, is to use the User Class command to mark the classes. You just have to mark the MI parents and the leaf class you are focusing on, then use the Minimal Tree command to reduce the tree to the User Classes and their parents.

Editing

Most of the editing features are available in both the editing area of the Browser windows, and the full File windows used to display an entire source file. The File windows also provide an MPW-style Markers menu, which shows user-selected markers as well as auto-generated markers for each method and structure definition.

Comprehensive search and replace operations are of course available. One nice touch is an effective keyword search, by searching for known entities in the dictionary. This includes class and method names and non-OOP structure names, depending on parsing preferences. I was a little disappointed to see that the grep search only allows MPW syntax and not the standard UNIX characters. However, the graphical constructor of grep queries is a great help.

Figure 6. C++ Style Settings for Editing Areas.

Keyword Color and Styling

Color and font styling in editors is a contentious issue. Figure 6 shows the range of styling controls. I’m very much a fan of subtle color coding. I like suppressing my comments slightly using a violet shade, so extensive commenting doesn’t crowd out the code. Silly errors with nested comments are immediately obvious with such color coding, and basic syntactic errors leap out at you in glaring red. If you tend to be a slightly sloppy typist (or occasionally work with a child on your lap) then error highlighting is a great time saver, compared to running the compiler.

Lookups and Completion

I’m forever looking up templates for complex toolbox functions - sometimes I think I bought my second monitor just to run Think Reference. As well as the common style of command-doubleclick to go directly to a reference, OM has Find and Paste Method Call. This feature looks up definitions from your methods, open 411 files and Think Reference (in that order). Best of all, it is not case-sensitive. For example:

• type getfinfo and hit command-shift-J

• Think Reference is invoked to complete the line to read:

GetFInfo(fileName,vRefNum,&fndrInfo)

C Preprocessor Ignorance and Compiler Specifics

The most confusing issue I encountered was that OM doesn’t understand the C preprocessor. This statement seems silly when you start - the syntax highlighting clearly picks out compiler directives and italicizes the False branch in #if statements.

OM does understand the structure of #if statements and has a few predefined True and False constants. It does not understand #define, so if you have any macros that are used in the same sense as normal C++ keywords or functions, then you must define them manually. (Note: ACI say v3 will have full parsing.) The C\C++ submenu of the Settings menu allows you to define four kinds of macros:

• Null Macros (#define Macro);

• Identity Macros (#define Macro(x) x);

• Ignore Macros (#define Macro(x));

• Keyword Macros (redefine C++ and C keywords, from a popup menu).

Something that is very poorly documented is how to cope with compiler extensions such as CodeWarrior’s ONEWORDINLINE. Although these are compiler keywords, and not macros, any such extension to C++ v3 syntax must be treated as a macro. As described below, you need to add a number of such macros to successfully parse the PowerPlant classes (and I’m still adding to the list for zApp for Windows).

Apparent bugs in the parsing

#if !defined(MC_PLATFORM)
#define PLATFORM_MACINTOSH
#define MC_PLATFORMPLATFORM_MACINTOSH
#endif

Defaults to a true branch, so you would expect PLATFORM_MACINTOSH to be known. However, remember that #define is not really understood by the OM parser, so may think you should define PLATFORM_MACINTOSH as a True & Defined Symbol yourself.

No: this is still not good enough as the OM #define parsing doesn’t understand logical operators. Having defined _INTELC32_ as a False Symbol by hand, you would expect the #defines in the following code to be included. They’re not, but it doesn’t really matter.

You don’t have to worry too much about whether #if or #else branches are taken if the only things bracketed are #defines, as they are ignored. Remember, any preprocessor symbols that have syntactic significance must be manually defined.

#if defined(_INTELC32_) || defined(PLATFORM_MACINTOSH)
#define far
#define near
#define huge
#define cdecl
#endif

So, after all the above worrying over how to get the preprocessor #if branching correct, we still have to go through and manually add a definition of w_cdecl, to get the OM parser to accept the following line:

typedef voidw_cdecl (*MFUNC) (char *msgtext);

CodeWarrior Support

OM Universal v2.5 is advertised as supporting CodeWarrior and the on-disk Addendum includes specific instructions. However, I found the project commands to synchronize and load files from projects were disabled. ACI US Technical support (via CompuServe) have confirmed this is due to CodeWarrior still not providing full AppleEvents for external editors.

Parsing Problems

CodeWarrior defines a number of compiler extensions. Most of these are keywords that can be simply added to the OM macro definitions, as shown below. However, I was unable to resolve a way to get Object Master to accept constructs such as the following, where the :__D0 is an indicator that the parameter is passed in a register. One problem is that the macro definitions dialog doesn’t allow the colon character as part of a macro name.

 
static long RestoreA4(long:__D0):__D0 = 0xC18C;
Defined Ignore Macros for the following (v2.5.2 knows the xxWORDINLINE's):

ONEWORDINLINE
TWOWORDINLINE
THREEWORDINLINE
FOURWORDINLINE
FIVEWORDINLINE
SIXWORDINLINE
CallComponentRoutineProc
ComponentCallNow
NewComponentRoutineProc

Define Null Macros (in addition to those such as pascal already in a new project):

_C_LIB_DECL
_END_C_LIB_DECL
_EXTERN_C
_END_EXTERN_C
THREAD_INLINE_PROC

MPW May Rescue Us

When the 68k CodeWarrior MPW tools arrive, missing in CW4, things may change. Given the high level of MPW integration, OM users will probably ignore the CodeWarrior IDE and build directly using the MPW tools. This will be a quick fix to the problems of integrating with CodeWarrior projects, but I hope both options will be available in future release of OM.

Scripting and Customizing

AppleScript Built-In

AppleScript is very tightly integrated into OM, although unfortunately not recordability. There is a Startup Folder which can contain scripts to be executed to customize the OM environment, or perform any other startup action. The initial scripts in this folder add an AppleScript menu to the OM main menu, with a number of useful scripts. eg: List Methods With Parameter which searches all methods and creates a list windoid of all matches, for the parameter type you enter (warning: choosing something general like Handle takes a few minutes on a IIci).

There are some eight pages of class definitions for AppleScript classes. Between them, they seem to offer control over the content and attributes of most components. The only omission that bothers me is the 411 Documentation files. It would be nice to have scripted retrieval of documentation, to aid in building reference manuals. I assume the MPW experts will be able to cope with this but I feel a little left out.

Executing AppleScripts is very well thought out. Apart from the AppleScript menu, scripts can be entered into the MPW-like Worksheet window and activated with a command-Enter. If you are really in a hurry, any piece of text in an editing window can be executed with the Execute in AppleScript item on the Text menu.

MPW Support

One thing that disappointed me about the tight links between OM and MPW is that you have to specify MPW as your compiler. For example, the editing windows allow invocation of the MPW tools CDent and PasMat. If you have CodeWarrior or Think Pascal selected as your compiler, you have to enter Preferences and change this to MPW Shell or ToolServer before the Reformat command or icon work.

As part of the AppleScript support, OM defines a rich suite of AppleEvents. The long list of bundled MPW Scripts and Tools includes the OM_SendAE tool. This lets you exert the same scripting control from MPW as AppleScript or Frontier.

MPW is OM’s native environment. As well as driving the various compiler and linker tools, OM has support for Jasik’s Incremental Build System (an incremental linker). Projector support for version control is cleanly provided with a popup menu on the bottom left corner of File and Browser windows.

Stationery and Custom Resources

OM fully supports System 7 stationery settings. In addition to creating Stationery documents, you can put a Project Options file in the Preferences folder to set your standard project options. This includes basic settings as well as automatically including whatever files are part of your Project Options.

For those wishing permanent change to Object Master’s defaults and appearances, the elegant solution is the OM Customization file. This is a resource file, initially blank, which is opened straight after the application. A detailed chapter of the manual lists the resource numbers and types you can add to this file, to override the standard ones without fear of conflict.

Windows Plans

From the number of postings I’ve seen in comp.lang.c++ asking about object browsers, the following CompuServe posting should come as very good news (I wonder how they ported from a MacApp v2 product?):

23 Aug 1994 3:43:11 From: ACI US Tech Support 76207,1331

We will be releasing a Windows version next quarter. We have just finish the Alpha Phase of testing. The Windows version will support all major compilation systems on the PC. Borland, Microsoft, Symantec, etc.

There will be major feature that will allow the user to do true cross platform development.

- Joe Levenson, ACI US

Conclusions and Wish-List

Writing this review was a great excuse to go romp through Object Master’s exhaustive (and exhausting) feature list. I hope I’ve convinced a majority of you that the product is worth looking at, and I salute Metrowerks for including a demo version. Since writing the review, I’ve also used OM to learn the zApp framework. It has been worth buying just for the time saved in this project!

ACI seem to be very interested in maintaining OM and there has been enough public criticism that I would expect the problems with parsing bad code to be fixed very soon (Note: v2.5.2 includes some improvements and is much more stable). ACI’s Technical Support in the ACIUS forum on CompuServe is free and fairly quick to respond. Their response to this article helped me clarify a few points about the fixes in v2.5.2 and they’ve annotated the wish list shown below.

The increased emphasis on C++ should lead them to improve CodeWarrior and general C++ support, and rectify the lack of Getting Started docs. Here’s my wish list for features in OM version 2.6 (CMaster users may feel a sense of deja-vu):

High on the v3 list

• Splitter bar or bars in the File editor

• Block commenting with enough intelligence to allow commenting out a block and then reversing the process without losing existing comments

Already in native version, and in next 68k minor release

• Script or other support for adding and removing line feeds to ease transition between Mac and DOS

• Make it possible/easy to copy macro definitions between projects. (Drag-n-drop)

Under Consideration

• Tree browser Focus on Class includes multiple-inherited parents

• Applescript control over 411 Documentation supported as a property of Method and Class AppleScript classes.

Good Ideas

• Enable users of other compilers to run MPW scripts (this would let us use the MPW tools such as Mac2DOS)

• Drag-and-drop in the Segment Window shouldn’t require holding down Option to reassign methods to segments

• Smarter indentation control, rather than having to run the external MPW indent

• Tree browser allows restrict by color, not just User Class

ACIUSoffers a free demo disk of Object Master. You can contact them at ACIUS at (800) 384-0010 or (408) 252-4444 voice, (408)252-0831 fax, AppleLink D4444, or mail them at ACIUS, 20883 Stevens Creek Blvd., Cupertino CA 95014.