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

TotalFinder 1.12.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Features... Read more
Duet 2.3.0.3 - Use your iPad as an exter...
Duet is the first app that allows you to use your iDevice as an extra display for your Mac using the Lightning or 30-pin cable. Note: This app requires a $9.99 iOS companion app. Version 2.3.0.3:... Read more
FileMaker Pro Advanced 18.0.3 - Powerful...
FileMaker Pro Advanced is the tool you use to create a custom app. You also use FileMaker Pro Advanced to access your app on a computer. Start by importing data from a spreadsheet or using a built-in... Read more
OsiriX Lite 10.0.6 - 3D medical image pr...
OsiriX Lite is an image processing software dedicated to DICOM images (".dcm" / ".DCM" extension) produced by medical equipment (MRI, CT, PET, PET-CT, ...) and confocal microscopy (LSM and BioRAD-PIC... Read more
Ableton Live 10.1.5 - Record music using...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Burn 2.7.8 - Easily burn data, audio, vi...
Burn... There are a lot of ways to approach burning discs. Burn keeps it simple, but still offers a lot of advanced options. Create data discs with advanced data settings like, file permissions, the... Read more
Malwarebytes 4.0.30.3073 - Adware remova...
Malwarebytes (was AdwareMedic) helps you get your Mac experience back. Malwarebytes scans for and removes code that degrades system performance or attacks your system. Making your Mac once again your... Read more
Acorn 6.5.3 - Bitmap image editor.
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Fantastical 2.5.13 - Create calendar eve...
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... Read more
A Better Finder Rename 11.05 - File, pho...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more

Latest Forum Discussions

See All

Eternal Warfare is a new idle clicker fo...
Idle games are a popular genre on mobile, they might not be to everyone's taste but they're made with such regularity and receive a lot of downloads, so it's hard to argue it's not big business. Eternal Warfare is set to join the sea of idle games... | Read more »
New heroes and balance updates set to ar...
It feels like Hearthstone: Battlegrounds only launched yesterday, and already the auto batter addition to Blizzard's megahit card game is set to receive new heroes and balance updates. [Read more] | Read more »
Pre-register for Hello Kitty AR: Kawaii...
Hello Kitty — the cute cat that launched a multi-billion-pound franchise — has been brought to life… sort of. Sanrio has teamed up with the Bublar Group to create a new mobile game that uses AR tech to turn the real world into Hello Kitty’s... | Read more »
Gorgeous and tranquil puzzler Spring Fal...
One-man indie studio SPARSE//GameDev has now launched its tranquil puzzler, Spring Falls. It's described as "a peaceful puzzle game about water, erosion, and watching things grow". [Read more] | Read more »
Black Desert Mobile gets an official rel...
Pearl Abyss has just announced that its highly-anticipated MMO, Black Desert Mobile, will launch globally for iOS and Android on December 11th. [Read more] | Read more »
Another Eden receives new a episode, cha...
Another Eden, WFS' popular RPG, has received another update that brings new story content to the game alongside a few new heroes to discover. [Read more] | Read more »
Overdox guide - Tips and tricks for begi...
Overdox is a clever battle royale that changes things up by adding MOBA mechanics and melee combat to the mix. This new hybrid game can be quite a bit to take in at first, so we’ve put together a list of tips to help you get a leg up on the... | Read more »
Roterra Extreme - Great Escape is a pers...
Roterra Extreme – Great Escape has been described by developers Dig-It Games as a mini-sequel to their acclaimed title Roterra: Flip the Fairytale. It continues that game's tradition of messing with which way is up, tasking you with solving... | Read more »
Hearthstone: Battlegrounds open beta lau...
Remember earlier this year when auto battlers were the latest hotness? We had Auto Chess, DOTA Underlords, Chess Rush, and more all gunning for our attention. They all had their own reasons to play, but, at least from where I'm standing, most... | Read more »
The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »

Price Scanner via MacPrices.net

B&H offers $100 discounts on 4-Core and 6...
B&H Photo has new 4-Core and 6-Core Mac minis in stock and on sale today for $100 off Apple’s MSRP. Prices start at $699. Overnight shipping is free to many addresses in the US: – 3.6GHz Quad-... Read more
Save $200 today on a 2019 13″ MacBook Air wit...
Apple has a full line of Certified Refurbished 2019 13″ MacBook Airs available starting at only $929 and up to $200 off the cost of new Airs. Each MacBook features a new outer case, comes with a... Read more
New Verizon Pre-Black Friday 2019 deal: Buy o...
Buy one new Apple iPhone 11 model or 2018 iPhone XS model at Verizon and get a second one for free. One new line of service required. Offer is valid from November 21, 2019 to November 27, 2019. Here... Read more
AirPods with Wireless Charging Case on sale t...
Abt Electronics has 2019 AirPods with the Wireless Charging Case on sale today for $163 shipped. Their price is $36 off Apple’s MSRP, and it’s currently the cheapest price for these AirPods from any... Read more
Apple continues to offer 2017 13″ Dual-Core n...
Apple has Certified Refurbished 2017 13″ 2.3GHz Dual-Core non-Touch Bar MacBook Pros still available starting at $1019. An standard Apple one-year warranty is included with each model, outer cases... Read more
Save up to $120 on the new 16″ MacBook Pro at...
Apple’s resellers are starting to receive stock of new 16″ MacBook Pros, and the first set of sales & deals are now available: (1) Amazon 16″ MacBook Pros start on sale for $100-$116 off Apple’s... Read more
Apple Watch Series 3 models on sale at Amazon...
Amazon has Apple Watch Series 3 GPS models on sale for $30 off MSRP, starting at only $169. There prices are the lowest we’ve ever seen for these models from any Apple reseller. Choose Amazon as the... Read more
The ‘Mac Potpourri’ Mailbag: Edition #1- Info...
COMMENTARY: 11.20.19- Welcome to the inaugural edition of the “Mac Potpourri” Mailbag where we take a look at correspondence received from readers of this column from all over the world who write in... Read more
13″ 2.4GHz MacBook Pros available for up to $...
Apple has a full line of Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros available starting at $1529 and up to $300 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
New at T-Mobile: Switch to T-Mobile, and get...
T-Mobile is offering a free 64GB iPhone 8 for new customers who switch to T-Mobile and open a new line of service. Eligible trade-in required, and discount applied over a 24 month period. The fine... Read more

Jobs Board

Best Buy *Apple* Computing Master - Best Bu...
**747303BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 001413-Cypress-Store **Job Description:** **What Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**743221BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000230-Greenwood-Store **Job Description:** At Best Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**747338BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000254-Superstition Springs-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**745516BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001101-Manhattan-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**746655BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 002518-Atlantic Center-Store **Job Description:** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.