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
$567.77
Apple Inc.
+43.02
MSFT
$39.86
Microsoft Corpora
+0.17
GOOG
$525.16
Google Inc.
-1.78

MacTech Search:
Community Search:

Software Updates via MacUpdate

Ember 1.5.1 - Versatile digital scrapboo...
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
Cyberduck 4.4.4 - FTP and SFTP browser....
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
TechTool Pro 7.0.3 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
MacFamilyTree 7.1.6 - Create and explore...
MacFamilyTree gives genealogy a facelift: it's modern, interactive, incredibly fast, and easy to use. We're convinced that generations of chroniclers would have loved to trade in their genealogy... Read more
EtreCheck 1.9.9 - For troubleshooting yo...
EtreCheck is a simple little app to display the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support... Read more
TeamViewer 9.0.28116 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
DiskAid 6.6.3 - Use your iOS device as a...
DiskAid is the ultimate transfer tool for accessing the iPod, iPhone or iPad directly from the desktop. Access data such as: music, video, photos, contacts, notes, call history, text messages (SMS),... Read more
Viber 4.1.0 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device,... Read more
Apple iOS 7.1.1 - The latest version of...
The latest version of iOS can be downloaded through iTunes. Apple iOS 7 brings an all-new design and all-new features. Simplicity Simplicity is often equated with minimalism. Yet true simplicity is... Read more
1Password 4.3 - Powerful password manage...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more

Latest Forum Discussions

See All

Pen & Ink Review
Pen & Ink Review By Jennifer Allen on April 24th, 2014 Our Rating: :: CONVENIENT ARTISTRYiPad Only App - Designed for the iPad Pen & Ink is an ideal way to sketch down some visual ideas or simply spark your imagination.   | Read more »
Sonic & All-Stars Racing Transformed...
Sonic & All-Stars Racing Transformed Now Free, to Add New Iconic Characters and Elements Posted by Tre Lawrence on April 24th, 2014 [ | Read more »
Soccer Rally 2 Review
Soccer Rally 2 Review By Carter Dotson on April 24th, 2014 Our Rating: :: GOALKEEPINGUniversal App - Designed for iPhone and iPad Soccer Rally 2 is the most serious vehicular soccer game ever created.   | Read more »
Galaxy Conquerors Review
Galaxy Conquerors Review By Jennifer Allen on April 24th, 2014 Our Rating: :: RETRO SHOOTINGUniversal App - Designed for iPhone and iPad Old school shooting is fun but inaccurate in Galaxy Conquerors.   | Read more »
Yomi Review
Yomi Review By Rob Thomas on April 24th, 2014 Our Rating: :: C-C-C-COMBO BREAKERiPad Only App - Designed for the iPad Round One – Fight! No quarters required for this iOS adaptation of a tabletop adaptation of the arcade fighting... | Read more »
Injustice: Gods Among Us Updated with Ne...
Injustice: Gods Among Us Updated with New Characters, Leaderboards, Gear, and Online Multiplayer Posted by Rob Rich on April 24th, 2014 [ | Read more »
Spin It Review
Spin It Review By Jordan Minor on April 24th, 2014 Our Rating: :: SPIN ME RIGHT ROUNDUniversal App - Designed for iPhone and iPad Spin It has a fine puzzle game model, but its execution lacks energy.   | Read more »
Productivity App NoteSuite is Having its...
Productivity App NoteSuite is Having its Biggest Sale Ever, Just for One Week Posted by Rob Rich on April 24th, 2014 [ permalink ] | Read more »
Wayward Souls Review
Wayward Souls Review By Carter Dotson on April 24th, 2014 Our Rating: :: CARRY ON, WAYWARD SONUniversal App - Designed for iPhone and iPad Wayward Souls is a roguelike-inspired action-RPG that sets a high bar for other games to... | Read more »
The Sandbox Gets Update, Receives New Ca...
The Sandbox Gets Update, Receives New Campaign and New Elements Posted by Tre Lawrence on April 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »

Price Scanner via MacPrices.net

Strong iPhone Sales Drive Apple Record March...
Apple on Wednesday announced financial results for its fiscal 2014 second quarter ended March 29, 2014. The Company posted quarterly revenue of $45.6 billion and quarterly net profit of $10.2 billion... Read more
Award-Winning NoteSuite Productivity App is $...
Minneapolis based Theory.io has announced an 80-Percent Markdown NoteSuite for iPad. NoteSuite helps users stay organized by capturing their notes, to-dos and documents in one organized place.... Read more
16GB 1st generation iPad mini available for $...
Radio Shack has a select number of refurbished 1st generation 16GB WiFi iPad minis available for $199.99 on their online store. Choose free shipping or free ship-to-store. We expect these to sell out... 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 $1099 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
iPad Sales “Lull” A Reality Correction Of Unm...
I have lots of time for Jean-Louis Gassée, the former Apple Computer executive (1981 to 1990) who succeeded Steve Jobs as head of Macintosh development when the latter was dismissed in 1985. Mr.... Read more
Apple Makes OS X Betas Available To All – Wit...
Apple’s OS X Beta Seed Program, which lets you install the latest pre-release builds, try it out, and submit your feedback, is now open to anyone who wants to sign on rather than to developers and... Read more
Apple Releases iOS 7.1.1 Update
The latest iOS 7.1.1 update contains improvements, bug fixes and security updates, including: • Further improvements to Touch ID fingerprint recognition • Fixes a bug that could impact keyboard... Read more
Logitech Announces Thinner, Lighter, More Fle...
Logitech has announced an update to its Ultrathin for iPad Air, iPad mini and iPad mini with Retina display, improving the flexibility and design of its award-winning predecessor with an even thinner... Read more
Logitech Introduces Hinge, Big Bang and Turna...
Logitech has announced expansion of its tablet product line with three new cases – the Logitech Hinge, the Logitech Big Bang and the Logitech Turnaround – each for the iPad Air, iPad mini and iPad... Read more
WaterField’s Rough Rider Leather Messenger Ba...
WaterField Designs have announced the new 15-inch size of their popular Rough Rider leather messenger bag, a vintage-looking bag that combines Old West charm and ruggedness with distinctly modern... 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* 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
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of 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* 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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.