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.

 
AAPL
$524.94
Apple Inc.
+5.93
MSFT
$40.01
Microsoft Corpora
-0.39
GOOG
$536.10
Google Inc.
-20.44

MacTech Search:
Community Search:

Software Updates via MacUpdate

VMware Fusion 6.0.3 - Run Windows apps a...
VMware Fusion allows you to create a Virtual Machine on your Mac and run Windows (including Windows 8.1) and Windows software on your Mac. Run your favorite Windows applications alongside Mac... Read more
Tweetbot 1.5.1 - Popular iOS twitter cli...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Mac DVDRipper Pro 4.1.7 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
PDFpenPro 6.2 - Advanced PDF toolkit for...
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Create... Read more
PDFpen 6.2 - Edit and annotate PDFs with...
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
Monolingual 1.5.9 - 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. It requires a 64-bit capable Intel-based Mac and at least... Read more
Maya 2015 - Professional 3D modeling and...
Maya is an award-winning software and powerful, integrated 3D modeling, animation, visual effects, and rendering solution. Because Maya is based on an open architecture, all your work can be scripted... Read more
Starcraft II: Wings of Liberty 1.1.1.180...
Download the patch by launching the Starcraft II game and downloading it through the Battle.net connection within the app. Starcraft II: Wings of Liberty is a strategy game played in real-time. You... Read more
Sibelius 7.5.0 - Music notation solution...
Sibelius is the world's best-selling music notation software for Mac. It is as intuitive to use as a pen, yet so powerful that it does most things in less than the blink of an eye. The demo includes... Read more
Typinator 5.9 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more

Latest Forum Discussions

See All

Have a Special Dead Trigger 2 Easter Bas...
Have a Special Dead Trigger 2 Easter Basket Full of Goodies, Courtesy of Madfinger Games Posted by Rob Rich on April 18th, 2014 [ permalink ] Dead Trigger 2 | Read more »
Almost All of Playdek’s Library is on Sa...
Almost All of Playdek’s Library is on Sale Right Now, and You Should Check it Out Posted by Rob Rich on April 18th, 2014 [ permalink ] Playdek has released quite a few great iOS ports of board and card games over the years, and now most of them... | Read more »
Zynga Launches Brand New Farmville Exper...
Zynga Launches Brand New Farmville Experience with Farmville 2: Country Escape Posted by Tre Lawrence on April 18th, 2014 [ permalink ] | Read more »
David. Review
David. Review By Cata Modorcea on April 18th, 2014 Our Rating: :: MINIMALISTIC IN A DIFFERENT WAYUniversal App - Designed for iPhone and iPad David is a minimalistic game wrapped inside of a soothing atmosphere in which the hero... | Read more »
Eyefi Unveils New Eyefi Cloud Service Th...
Eyefi Unveils New Eyefi Cloud Service That Allows Users to Share Media Across Personal Devices Posted by Tre Lawrence on April 18th, 2014 [ permalink ] | Read more »
Tales from the Dragon Mountain: The Lair...
Tales from the Dragon Mountain: The Lair Review By Jennifer Allen on April 18th, 2014 Our Rating: :: STEADY ADVENTURINGiPad Only App - Designed for the iPad Treading a safe path, Tales from the Dragon Mountain: The Lair is a... | Read more »
Yahoo Updates Flickr App with Advanced E...
Yahoo Updates Flickr App with Advanced Editing Features and More Posted by Tre Lawrence on April 18th, 2014 [ permalink ] | Read more »
My Incredible Body - A Kid's App to...
My Incredible Body - A Kid's App to Learn about the Human Body 1.1.00 Device: iOS Universal Category: Education Price: $2.99, Version: 1.1.00 (iTunes) Description: Wouldn’t it be cool to look inside yourself and see what was going on... | Read more »
Trials Frontier Review
Trials Frontier Review By Carter Dotson on April 18th, 2014 Our Rating: :: A ROUGH LANDINGUniversal App - Designed for iPhone and iPad Trials Frontier finally brings the famed stunt racing franchise to mobile, but how much does its... | Read more »
Evernote Business Notebook by Moleskin I...
Evernote Business Notebook by Moleskin Introduced – Support Available in Evernote for iOS Posted by Tre Lawrence on April 18th, 2014 [ permalink ] | Read more »

Price Scanner via MacPrices.net

Deal Alert! 13-inch MacBook Pro on sale for $...
Best Buy has the 13″ 2.5GHz MacBook Pro on sale for $999.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $200 off MSRP. Price is valid... Read more
Free HopTo 2.2 Helps Enhance Your Productivit...
The HopTo app helps you do more on your iPad by providing more and easier adaccess to files and documents. Version 2.2 adds Egnyte and HopTo’s Mac OSX File Connector. If you already have the hopTo... Read more
National Distracted Driving Awareness Month:...
As the country recognizes National Distracted Driving Awareness Month, Sprint is reminding wireless consumers to focus on driving while behind the wheel, to not text or email while driving, and to... Read more
13-inch 2.4GHz Retina MacBook Pro available f...
Abt has the 13″ 2.4GHz 128GB Retina MacBook Pro available for $1229 including free shipping. Their price is $70 off MSRP. Read more
iMacs on sale for up to $160 off MSRP this we...
Best Buy has iMacs on sale for up to $160 off MSRP for a limited time. Choose free home shipping or free instant local store pickup (if available). Prices are valid for online orders only, in-store... Read more
iPad Airs on sale this weekend for up to $100...
Best Buy has WiFi iPad Airs on sale for $50 off MSRP and WiFi + Cellular iPad Airs on sale for $100 off MSRP on their online store for a limited time, with prices now starting at $449. Choose free... Read more
Apple restocks refurbished Mac minis starting...
The Apple Store has restocked Apple Certified Refurbished Mac minis for up to $150 off the cost of new models. Apple’s one-year warranty is included with each mini, and shipping is free: - 2.5GHz Mac... Read more
Hyundai Brings Apple CarPlay To The 2015 Sona...
Hyundai Motor America has announced it will bring Apple CarPlay functionality to the 2015 Sonata. CarPlay is pitched as a smarter, safer and easier way to use iPhone in the car and gives iPhone users... Read more
Updated iPads Coming Sooner Than We Had Thoug...
MacRumors, cites KGI securities analyst Ming Chi Kuo, well-respected as an Apple product prognisticator, saying that Apple will introduce an upgraded iPad Air and iPad mini in 2014/Q3, meaning the... Read more
Toshiba Unveils New High And Low End Laptop M...
Toshiba has announced new laptop models covering both the high-end and low-end of the notebook computer spectrum. Toshiba 4K Ultra HD Laptop Toshiba’s new Satellite P55t features one of the world’s... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Inc. Research Data Specialist - Appl...
…of Worldwide Market Research & Intelligence. The team is responsible for conducting Apple branded consumer market research. It is also responsible for analyzing data Read more
*Apple* Automotive Parts Department position...
Apple Automotive is one of the fastest growing dealer…and it shows. Consider making the switch to the Apple Automotive Group today! At Apple Automotive, we Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Retail - Manager - Holyoke - Apple I...
Job Summary Keeping an Apple Store thriving requires a diverse set of leadership skills, and as a Manager, you’re a master of them all. In the store’s fast-paced, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.