TweetFollow Us on Twitter

Commands and Undo CPX
Volume Number:11
Issue Number:1
Column Tag:Visual Programming

Commands and Undo in Prograph CPX

Command objects to do, redo, and undo

By Kurt Schmucker, Apple Computer, Inc.

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

When the Macintosh first came out in ‘84, there was one feature that users loved and developers hated: undo. For users, knowing that any action could be undone reduced dramatically the level of tension associated with using a new feature in a familiar application, with using a new app, or even with using a computer in general. Developers, unfortunately, had to implement this great functionality, and it wasn’t easy. Storing sufficient state in an event-driven application so that any user action could be undone was simply very difficult.

Command objects in MacApp 1.0 offered a way around this problem - a way that was easy for developers both to comprehend and to implement. A command object is an encapsulation of a user request for some action. It stores enough information to be able to perform the action, to be able to undo the action, and to be able to redo the action, and the methods of that command object perform exactly these functions. In response to a user action, your code allocates an appropriate command object, initializes that object, and then returns that object to the framework. The framework will immediately send the “DoIt” message to this object to have the desired action performed. The framework will hold onto that command object and will automatically send the “UndoIt” and “RedoIt” messages to the object if the user chooses the Undo or Redo menu items from the Edit menu. The developer is completely relieved of the responsibility for the run-time handling of Undo.

To illustrate these ideas, I have implemented an enhanced version of the MiniQuadWorld [1] application in CPX. The Prograph version of this app is on the source code disks and the online sites, along with the full source code (both in standard Prograph project and section files - for those of you who have CPX - and in PICTs for those of you who don’t). Also, the code for this application follows the latest version of the emerging Prograph coding style [2, 3].

Brief Review of Commands in MacApp

Both MacApp and CPX have basically the same approach to menu operation, so let’s do a quick review of command handling in MacApp 2 and MacApp 3 before we talk about the details of CPX’s. The command handling designs of MacApp 2 and MacApp 3 are different enough that we will examine each separately.

Commands in MacApp 2

You access the command handling apparatus of MacApp 2 with “hook” methods like DoMenuCommand and DoMouseCommand. (Figure 1 depicts the classes and important methods in this apparatus.) MacApp will call these methods when a menu item is chosen (DoMenuCommand) or when the user clicks in one of your views (DoMouseCommand). (In the case of DoMenuCommand, the argument will be the command number of the desired command. In the case of DoMouseCommand, the arguments will include the click point, from which you need to determine the right type of command.) You override these methods to allocate an instance of one of your command objects, and then return that object as the return value of the method. TApplication.PerformCommand will eventually call that command object’s DoIt method and, if it is an undoable command, will store the command object in TApplication.fLastCommand. Should the user choose the Undo menu item, then TApplication.DoMenuCommand will allocate an instance of TUndoRedoCommand which in turn will call the UndoIt method of the stored command. (Naturally, TUndoRedoCommand is not itself an undoable command.)

There is also a command queue for handling commands in the background and a mechanism for executing a command on a recurring basis.

Figure 1. The classes, methods, and fields that play important roles
in command handling in MacApp 2.

Most of the basic operations that MacApp performs automatically (or semi-automatically) like saving documents, reverting, quitting, opening and closing windows, and such are done with specific TCommand subclasses that are built into MacApp. These include the classes TAboutAppCommand, TCloseWindowCommand, TNewDocCommand, TRowSelectCommand (for a grid).

Commands in MacApp 3

The command apparatus for MacApp 3 is similar but somewhat more complex than that of MacApp 2. (Figure 2 depicts the classes and important methods in this apparatus.) There is an additional class, TCommandHandler, which provides the functionality for storing the last command, processing undo requests, etc. Since the main abstract superclasses that a programmer deals with (TApplication, TDocument, TView) are subclasses of TCommandHandler, this gives each of these objects the ability to undo its own last command. Thus each user context (window or document) has its own undo.

Figure 2. The classes, methods, and fields
that play important roles in command handling in MacApp 3.
(Note the addition of several new classes compared to that of MacApp 2.)

An additional change is that the old “hook” methods, DoMenuCommand and DoMouseCommand, no longer return the command object to the framework. Rather the programmer posts the command (using TApplication.PostCommand) which adds the command to the end of the event list. (TView and TDocument have a PostCommand method, but all these methods do is pass the command on to the application object.) These hook methods are still invoked by the framework, however, so that your code knows the appropriate time to instantiate a new command object.

As in MacApp 2, most of the basic operations that MacApp performs automatically (or semi-automatically) like saving documents, reverting, publishing and subscribing, etc. are done with specific TCommand subclasses that are built into MacApp. These include the classes TQuitCommand, TPrintCommand, TNewSubscriberCommand, TShowTearOffWindowCommand, and TECutCopyCommand.

Commands In CPX

Approach

The CPX approach to commands is somewhere between that of MacApp 2 and MacApp 3. In CPX there is a global command and event handler (Commander) which processes commands by executing their Do methods and processes events by passing them to a special event handler that it owns. Figure 3 shows some of the classes and methods important to the CPX command handling.

Figure 3. The classes, methods, and fields
that play important roles in command handling in Prograph CPX.
Note that Prograph’s approach contains ideas from
both the MacApp 2 and MacApp 3 algorithms.

Figure 4. The Click Behavior editor.
Note that this allows the programmer to, in effect,
custom design the hook method
for the processing of this mouse event.

There are no hook methods in CPX for returning the newly instantiated command objects to the framework. Instead, the commands are posted. Unlike MacApp 3, commands can post themselves. In addition, there is no need for hook methods like those in MacApp 3, since the Behavior mechanism in CPX provides a way for your code to get control when a user event like choosing a menu item or clicking in a view occurs. In fact, the Behavior editor can reduce the need for some of the code you would have to have written in a MacApp implementation, and in some simple cases, can even obviate the need for any code at all. Figure 4 shows the Click Behavior editor for a view. What this editor enables the programmer to do is, in effect, to custom design the hook method to be used in exactly this situation. As part of the specification of this behavior, you can have an instance of any class allocated, or have the value of any window item obtained, among many other things.

Figure 5. The basic command processing method in CPX.
(The comments have been added and the names of some of the locals changed
to make these clearer as static figures.)

In CPX, posting an ordinary command does not enter it into a list for later processing, but rather immediately causes the Commander to execute the command. There are special subclasses of Command, Deferred Task and Periodic Task, which will delay or repeat the execution of the command. Figure 5 shows some of the Prograph code from the ABC class library for command processing.

Periodic Task, a subclass of Command, is the mechanism for performing a recurring activity or processing during idle time. There is no use of Periodic Task in MiniQuadWorld+, but the Prograph implementation of the MacApp DemoDialogs sample program uses Periodic Tasks to refresh the view and target inspector windows. (CPX DemoDialogs was described in the March/April ‘94 issue of FrameWorks).

Unlike MacApp, Prograph class library itself doesn’t use commands very much. Features like printing, closing windows, and quitting the application, etc. for which MacApp has a specific TCommand subclass, CPX just uses its behavior mechanism to perform directly. For example, in MacApp 2, closing a window via the Close menu item is accomplished as follows: TWindow.DoMenuCommand is called by MacApp with the parameter cClose. This allocates a TCloseWindowCommand object, initializes it, and then returns it to MacApp. MacApp calls the command object’s DoIt method to tell the window’s main view to Close. This eventually causes the window, its document, etc. to close. Here is the MacApp 2 code:

TWindow.DoMenuCommand

FUNCTION TWindow.DoMenuCommand(
 aCmdNumber: CmdNumber): TCommand; OVERRIDE;
VAR
 aCloseWindowCommand: TCloseWindowCommand;
 oldObjectPerm:  BOOLEAN;
BEGIN
 DoMenuCommand := NIL;

 CASE aCmdNumber OF
 cClose:
 BEGIN
 oldObjectPerm := AllocateObjectsFromPerm(FALSE); 
 New(aCloseWindowCommand);
 IF AllocateObjectsFromPerm(oldObjectPerm) THEN;
 FailNil(aCloseWindowCommand);{ just in case }
 aCloseWindowCommand.ICloseWindowCommand(aCmdNumber,           
 SELF);
 DoMenuCommand := aCloseWindowCommand;
 END;
 OTHERWISE
 DoMenuCommand := INHERITED DoMenuCommand(aCmdNumber);
 END;
END;


TCloseWindowCommand.DoIt

PROCEDURE TCloseWindowCommand.DoIt;
BEGIN
 IF fView <> NIL THEN
 TWindow(fView).CloseByUser;
END;

The corresponding functionality in CPX is implemented with a behavior. Figure 6 shows the specification of this menu behavior, and the code that it calls. Since the MacApp TCloseWindowCommand is not an undoable command, there isn’t too much difference in the real functionality of these two approaches.

Figure 6. The implementation of the window closing functionality in Prograph CPX.
Note that this does not use a command object.

Implementing Some Command Subclasses

I implemented a very small sample app that contains three command classes. The app, MiniQuadWorld+, is a slight extension of the MiniQuadWorld app that I did years ago. This app merely displays five quadrilaterals and enables the user to select any number of them. The selected quadrilateral(s) can be rotated or removed. In addition, the interior color of any quad can be changed. Note that there is no capability for the entry of new quadrilaterals. This is basically what differentiates MiniQuadWorld from (full) QuadWorld. Figure 7 shows a screen dump of this app.

Figure 7. Screen dump of the MiniQuadWorld+ application. This application has three command subclasses that implement the user interactions with the quadrilaterals.

The three command classes in MiniQuadWorld+ are Rotate Quad Cmd, Clear Quad Cmd, and Recolor Quad Cmd. The rotation and clearing operations are accessed via a menu item to perform the desired operation on all the currently selected quads, and thus the associated commands are subclasses of Menu Behavior. Recoloring a quad is accomplished by option-clicking on the quad, and it not accessible via a menu. (Note that I am not implying that this is necessarily the best user interface, but rather that it demonstrates different ways in which commands might be instantiated.)

Because any number of quads can be selected and rotated and cleared, the only practical way to support undo for rotation is for each quadrilateral to store its old position. Storing this data in the command object itself would be cumbersome at best, and totally unmanageable at worst. It also turned out to simplify the implementation if each quadrilateral also recorded its selection state. Thus the Rotate Quad Cmd causes each selected quad to copy the current position values into the corresponding ‘old’ attributes, calculate the new position, and then cause a screen refresh. Undo just copies the old values back. Figure 8 shows the Do method for this class, and the method invoked by the menu behavior associated with the Rotate menu item.

The clear operation works by just removing the currently selected quads from the list of objects in the document, and its undo merely copies them back. The clear all quads operation is not implemented with a distinct TCommand subclass, but just selects all the quads and does a clear.

Recoloring a quad, since it is not a menu operation, works differently than all the other operations. The click method for the Quad Graphical View class checks to see if the option key is held down, and if so, allocates and posts an instance of Recolor Quad Cmd. The internals of the methods of that class are very similar to the other MiniQuadWorld+ command classes.

What Worked and What Didn’t

I was able to get every piece of functionality for MiniQuadWorld+ implemented and working correctly. The actions of rotating, clearing, or recoloring a quad are undoable, as is the clearing of all the quads. This isn’t too surprising given the limited features of this toy application, but it is still good to know. However, I did have to correct a significant bug in the CPX command processing to get the undo features of MiniQuadWorld+ to work the way they should.

Undo worked correctly as long as the user didn’t perform any action between the execution of the undoable command and the undo request. Any action. Scrolling the window, moving the window, and clicking in the window’s content region (among other things) all committed the previous command. This is an example of prematurely committing a command. (‘Committing’ a command is term from MacApp, not from CPX. It means that the user has just performed another undoable action, and since only single level undo is supported by MacApp, it is time to ‘throw away’ the last command object. Just before this is done, the command object is given one last chance to do any clean up processing. This last chance processing is implemented in TCommand.Commit. Then the framework disposes of the command object. CPX does not have the notion of committing a command, so it just ‘throws away’ the old command object at this time. (Since Prograph has garbage collection, throwing away the command just means letting go of any references to it.) Premature commitment of a command object is a bug that prematurely takes away from the user the ability to undo an action.

Figure 8. The code for instantiating, initializing, and performing
the Rotate Quad Cmd object.
This operation is initiated via a menu item and a CPX Menu Behavior
associated with that item invokes this code.

Figure 9. The correction to the Premature Command Commitment bug.
Rather than always executing a Window/Bring to Front,
the modified method first checks to see if the window is already the frontmost one.
If so (and this is often the case), then nothing is done.
This small fix eliminates most, but not all, of the premature commitments.

I have traced down this bug and implemented a new CPX section that corrects most, but not all, of the problem. The problem - at least insofar as I figured it out - was that the Window/Bring to Front method caused the last command to be committed and this method was being invoked MUCH too often. One portion of my fix (Figure 9) just checks to see if the window that is about to be brought to the front is already in front, and if it is, then the call to Window/Bring to Front is not made. Thus the last command is not committed, and everything works a little more as it should. This fix is in the Desktop class, so I have subclassed Desktop and overloaded the appropriate method (Desktop/Mouse Down). I also added a method to the Application subclass that causes this corrected Desktop subclass to be instantiated as the application’s Desktop instead of the normal one. Another part of my fix is a method to be placed into any movable window subclass. This Window method does the same sort of ‘Bring to Front, if necessary’ modification for the operation of moving the window.

I have packaged this patch in its own section so that I (and you) can easily add it to other applications until the next maintenance release of CPX by PI.

Both I and the PI Tech Support staff were surprised that such a bug as the premature command commitment discussed above had gone unreported until now - almost a year since CPX’s initial release. The only reason that we could think of for this was that CPX programmers were not putting undo support into their applications. Hopefully this section I have implemented and this article will encourage greater use of undo.

In addition, several other things were harder than expected. Having a visible indication that a quadrilateral was selected was tricky. This was not because it was hard to XOR small squares at the vertices of the quad, but rather because it was not easy to hook into the CPX drawing code in the correct way. Overriding the view or the window’s Draw method worked correctly for the initial draw of the window, but didn’t work for redraws. The solution I ended up using was to add code to the Quad/Draw method. Since a quad stores its own selection state, this was easy, and not too ugly a design.

Implementing the color changing was a little more difficult than necessary since there was no abstract superclass for commands initiated with the mouse rather than a menu item. What I wanted was something like the Menu Behavior class. I added a Mouse Behavior class and subclassed it for the Recolor Quad Cmd class.

Overall the impression that I got was that while it was not too difficult to do MacDraw-like user interfaces in CPX, this was not the design center for CPX. (Probably implementing database front ends was.) However, everything was doable.

References

[1] Schmucker, Kurt. Object Oriented Programming for the Macintosh, Hayden Book Company, 1986.

[2] Artman, Gerald. “More on Style in Prograph,” Visual News, April 1994, pp. 14-15.

[3] Schmucker, Kurt. “Toward a Prograph Coding Style,” Visual News, May 1994, pp. 16-17.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Duplicate Annihilator 5.7.5 - Find and d...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator... Read more
BusyContacts 1.0.2 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Capture One Pro 8.2.0.82 - RAW workflow...
Capture One Pro 8 is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 300 high-end cameras -- straight out of the box. It... Read more
Backblaze 4.0.0.872 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac.With unlimited storage available for $5 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Little Snitch 3.5.2 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Monolingual 1.6.4 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. If you use your computer in only one (human) language, you... Read more
CleanApp 5.0 - Application deinstaller a...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
Fantastical 2.0 - Create calendar events...
Fantastical is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event details... Read more
Cocktail 8.2 - General maintenance and o...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Direct Mail 4.0.4 - Create and send grea...
Direct Mail is an easy-to-use, fully-featured email marketing app purpose-built for OS X. It lets you create and send great looking email campaigns. Start your newsletter by selecting from a gallery... Read more

These are All the Apple Watch Apps and G...
The Apple Watch is less than a month from hitting store shelves, and once you get your hands on it you're probably going to want some apps and games to install. Fear not! We've compiled a list of all the Apple Watch apps and games we've been able to... | Read more »
Appy to Have Known You - Lee Hamlet Look...
Being at 148Apps these past 2 years has been an awesome experience that has taught me a great deal, and working with such a great team has been a privilege. Thank you to Rob Rich, and to both Rob LeFebvre and Jeff Scott before him, for helping me... | Read more »
Hands-On With Allstar Heroes - A Promisi...
Let’s get this out of the way quickly. Allstar Heroes looks a lot like a certain other recent action RPG release, but it turns out that while it’s not yet available here, Allstar Heroes has been around for much longer than that other title. Now that... | Read more »
Macho Man and Steve Austin Join the Rank...
WWE Immortals, by Warner Bros. Interactive Entertainment and WWE, has gotten a superstar update. You'll now have access to Macho Man Randy Savage and Steve Austin. Both characters have two different versions: Macho Man Randy Savage Renegade or Macho... | Read more »
Fearless Fantasy is Fantastic for the iF...
I actually had my first look at Fearless Fantasy last year at E3, but it was on a PC so there wasn't much for me to talk about. But now that I've been able to play with a pre-release version of the iOS build, there's quite a bit for me to talk... | Read more »
MLB Manager 2015 (Games)
MLB Manager 2015 5.0.14 Device: iOS Universal Category: Games Price: $4.99, Version: 5.0.14 (iTunes) Description: Guide your favorite MLB franchise to glory! MLB Manager 2015, officially licensed by MLB.com and based on the award-... | Read more »
Breath of Light (Games)
Breath of Light 1.0.1421 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1421 (iTunes) Description: Hold a quiet moment. Breath of Light is a meditative and beautiful puzzle game with a hypnotic soundtrack by... | Read more »
WWE WrestleMania Tags into the App Store
Are You ready to rumble? The official WWE WrestleMania app, by World Wrestling Entertainment, is now available. Now you can get all your WrestleMania info in one place before anyone else. The app offers details on superstar signings, interactive... | Read more »
Bio Inc's New Expansion is Infectin...
Bio Inc., by DryGin Studios, is the real time strategy game where you infect a human body with the worst virus your evil brain can design. Recently, the game was updated to add a whole lot of new features. Now you can play the new “Lethal”... | Read more »
The Monocular Minion is Here! Despicable...
Despicable Me: Minion Rush, by Gameloft, is introducing a new runner to the mix in their latest update. Now you can play as Carl, the prankster minion. Carl has a few new abilities to play with, including running at a higher speed from the start.... | Read more »

Price Scanner via MacPrices.net

13-inch 2.5GHz MacBook Pro (refurbished) avai...
The Apple Store has Apple Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.... Read more
Save up to $80 on iPad Air 2s, NY tax only, f...
 B&H Photo has iPad Air 2s on sale for $80 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $469.99 $30 off - 64GB iPad Air 2 WiFi: $549.99 $50 off - 128GB iPad... Read more
iMacs on sale for up to $205 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Färbe Technik Offers iPhone Battery Charge LI...
Färbe Technik, which manufactures and markets of mobile accessories for Apple, Blackberry and Samsung mobile devices, is offering tips on how to keep your iPhone charged while in the field: •... Read more
Electronic Recyclers International CEO Urges...
Citing a recent story on CNBC about concerns some security professionals have about the forthcoming Apple Watch, John Shegerian, Chairman and CEO of Electronic Recyclers International (ERI), the... Read more
Save up to $380 with Apple refurbished iMacs
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
Mac minis on sale for up to $75 off, starting...
MacMall has Mac minis on sale for up to $75 off MSRP including free shipping. Their prices are the lowest available for these models from any reseller: - 1.4GHz Mac mini: $459.99 $40 off - 2.6GHz Mac... Read more
College Student Deals: Additional $50 off Mac...
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through April 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more
Mac Pros on sale for up to $260 off MSRP
B&H Photo has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3719.99... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more

Jobs Board

DevOps Software Engineer - *Apple* Pay, iOS...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
Lead *Apple* Solutions Consultant - Retail...
**Job Summary** Job Summary The Lead ASC is an Apple employee who serves as the Apple business manager and influencer in a hyper-business critical Reseller's store Read more
*Apple* Pay - Site Reliability Engineer - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.