TweetFollow Us on Twitter

Undo, TCommand
Volume Number:6
Issue Number:11
Column Tag:Jorg's Folder

TCommand and Undo

By Jörg Langowski, MacTutor Editorial Board

“MacApp - TCommand and Undo”

The example MacApp program in the August and September columns gives us a starting point for explaining how to extend a MacApp application. One of the most important operations that well-written Macintosh programs should support is Undo; so in this column I will show you in more detail how to implement undoing of commands in MacApp.

To undo an operation done on some document, we have to remember the state of the document before the operation and restore that state. Sounds simple; the problem is that in a usual Macintosh application many parts of the program will be affected. The structure beneath MacApp, however, makes it very simple to implement Undo. For each operation that should be undoable, a ‘command object’ is created which is intelligent enough to remember what it has done to the document, and which contains an Undo method that uses this information to reverse the operation.

Using command objects

Before we review our particular command object’s methods and variables, let’s see how some of these command objects are used. When the mouse is clicked inside a MacApp view, the DoMouseCommand method of that view is called. In your definition of that method, you must define the mouse behavior that you want. The previous example knew only one behavior; when the ‘drawing’ icon in the palette was selected, one could draw a rounded rectangle, using a cross cursor.

The standard way of implementing the mouse behavior would then be:

- determine which command you want to execute, depending on where the mouse was clicked;

- create a new command object corresponding to the operation to be done, and check for errors with FailNIL;

- initialize the command object by calling its initialization method;

- and, finally, exit the DoMouseCommand method, returning the command object to the calling routine.

That command object is then used by MacApp to track the mouse and implement undo/redo. When it is no longer used, it will be deleted (so you don’t have to care about it anymore).

In our new example, we want to implement dragging of the rectangles. When the mouse is clicked inside one of the rectangles, moving it should not create a new rectangle, but drag the old one around. Therefore, we first have to write a routine that checks whether the mouse was clicked inside an existing object. This is done by a global routine, FindBox, which is used as a parameter to the ForEachShapeDo method of the TEDocument class, passing the parameters to FindBox through the structure aFindBoxStruct. (The way in which a routine can be applied to a list of shapes has been described in the previous example - C++ makes it a little more complicated than Pascal).

When the mouse has been clicked inside an existing shape (aFindBoxStruct.myBox is non-nil), we use the Dragger instead of the Sketcher object to implement the mouse behavior (see listing).

The TCommand class

Command objects are implemented through MacApp’s TCommand class. If you want to define some undoable operation, you have to derive a subclass of TCommand which implements that specific operation. The class TDragger is implemented below. It includes the methods IDragger, TrackMouse, DoIt, UndoIt, and RedoIt.

In DoMouseCommand, we first create a new TDragger object, and then initialize it, telling it which object is going to be dragged (itsBox). In the initialization method, that object’s pointer is copied into an instance variable (fBox), and the instance variables oldLocation and newLocation are set to their initial values.

After we return the Dragger object from our DoMouseCommand, the MacApp system will call its TrackMouse method. The variable aTrackPhase indicates whether we just pushed the mouse button, whether we are in the middle of a drag, or just released the button. We need to take action only after the button has been released; it is then that the shape is moved to its new location on the screen. We set the object’s coordinates to their new values (calculated from the starting and ending points of the mouse drag), change newLocation, and return from the routine. this is returned to the calling routine, which means that on the next call the same mouse tracker will be used.

Note that all we need to do in the mouse tracker is to change the coordinates of the dragged object. The actual move will be done by the DoIt method, which is called after the mouse drag is completed. DoIt simply invalidates the object’s old and new bounds rectangles, so that these regions will be updated (this is also done automatically by MacApp).

In UndoIt, we simply reset the coordinates back to the old location and then call DoIt; RedoIt changes the coordinates back to the new location and DoesIt.

So in fact, you see that undoing a simple operation like moving an object is made very simple by MacApp. The command object exists as long as no other undoable command is chosen; when you perform another action that might be undoable, MacApp frees the last command so that its information is lost. But before that, all parameters necessary to undo/redo the operation should be stored inside the command object and used if necessary.

A final remark to the ‘cmnu’ 128 resource: This is a pseudo-menu (never displayed in the menu bar), which contains ‘buzzwords’ that should appear after Undo in the Edit menu so that the user can see which command can be undone/redone. The buzzword is associated with the proper command through the command number, we define cDragBox = 3001 for this purpose. This definition must of course be included in both the Rez file and the C++ program. It is used by the ICommand method, where the menu behavior is initialized.

When you execute the example and drag one of the rectangles around, you might notice that the mouse behavior is somewhat strange. The object is not dragged by moving its gray outline around, as you would expect, but instead a ‘rubber band’ rectangle is drawn connecting the starting and ending points of the drag. This is the standard behavior of mouse move feedback in MacApp, and if we want something more fancy, we have to define it ourselves. Next month, I’ll show you how to implement such a ‘track feedback’ routine. Until then, happy hacking.

Listing 1: Changes to the V6#8 example to support shape dragging

class TDragger : public TCommand {

public:
 TTEDocument   *fTEDocument;
 TTextView*fTextView;
 TBox   *fBox; // the object being dragged
 Rect   oldLocation; // initial location of object 
 Rect   newLocation; // new location of object 
 pascal void IDragger(TBox *itsBox, 
 TTEDocument *itsDocument, TTextView *itsView);
 pascal struct TCommand *TrackMouse
 (TrackPhase aTrackPhase,
  VPoint *anchorPoint, VPoint *previousPoint, 
  VPoint *nextPoint, Boolean mouseDidMove);
 pascal void DoIt();
 pascal void RedoIt();
 pascal void UndoIt();
#ifdef qDebug
 virtual pascal void Fields
 (pascal void (*DoToField) (StringPtr fieldName,
  Ptr fieldAddr, short fieldType, void *link), 
 void *link);
#endif
};

struct FindBoxStruct {
 Point theMouse;
 TBox *myBox;
};

const int cDragBox = 3001;
 // command number for Box dragger object}

pascal void FindBox
 (TBox *aBox, FindBoxStruct *aFindBoxStruct)
{
 if (PtInRect
 (aFindBoxStruct->theMouse,&aBox->fLocation))
 { aFindBoxStruct->myBox = aBox; };
}

pascal struct TCommand *TTextView::DoMouseCommand
 (Point *theMouse,  EventInfo *info, Point *hysteresis)
{ 
 TSketcher *aSketcher;
 TDragger  *aDragger;
 FindBoxStruct aFindBoxStruct;
 
 if (fPaletteView->fIconSelected == kBox-kBox) 
 {
 // dragging support, JL 9/90
 aFindBoxStruct.theMouse = *theMouse;
 aFindBoxStruct.myBox = nil;
 
 fTEDocument->ForEachShapeDo
 ((DoToObject)FindBox,&aFindBoxStruct);
 
 if (aFindBoxStruct.myBox != nil)
 { 
 SysBeep(5);// drag it
 aDragger = new TDragger;
 FailNIL(aDragger);
 aDragger->IDragger(aFindBoxStruct.myBox,
  fTEDocument, this);
 return aDragger;
 }
 else
 {
 aSketcher = new TSketcher;
 FailNIL(aSketcher);
 aSketcher->ISketcher(fTEDocument, this);
 return aSketcher;
 }
 }
 else
 return inherited::DoMouseCommand
 (theMouse,info,hysteresis);
}

pascal void TDragger::IDragger
 (TBox *itsBox, TTEDocument *itsDocument,
  TTextView *itsView)
{
 TScroller *aScroller;

 aScroller = itsView->GetScroller(true);
 ICommand(cDragBox, itsDocument, 
 itsView, aScroller);
 fTEDocument = itsDocument;
 fTextView = itsView;
 fBox = itsBox;
 oldLocation = fBox->fLocation;
 newLocation = fBox->fLocation;
}

pascal struct TCommand *TDragger::TrackMouse
 (TrackPhase aTrackPhase, VPoint *anchorPoint,
  VPoint *previousPoint,  VPoint *nextPoint, 
  Boolean mouseDidMove)
{
 
 if ((aTrackPhase == trackRelease) 
 && mouseDidMove)
 {
 newLocation.top = oldLocation.top 
 + nextPoint->v - anchorPoint->v;
 newLocation.left = oldLocation.left 
 + nextPoint->h - anchorPoint->h;
 newLocation.bottom = oldLocation.bottom 
 + nextPoint->v - anchorPoint->v;
 newLocation.right = oldLocation.right 
 + nextPoint->h - anchorPoint->h;
 fBox->fLocation = newLocation;
 }
 return this;
}

pascal void TDragger::DoIt()
{
 fTextView->InvalidRect(&newLocation);
 fTextView->InvalidRect(&oldLocation);
}

pascal void TDragger::RedoIt()  
{  
 fBox->fLocation = newLocation;
 DoIt(); 
}

pascal void TDragger::UndoIt()
{
 fBox->fLocation = oldLocation;
 DoIt(); 
}


#ifdef qDebug
pascal void TDragger::Fields(pascal void (*DoToField)
  (StringPtr fieldName, Ptr fieldAddr, 
 short fieldType, void *link), void *link)
{
 DoToField(“\pTDragger”, nil, bClass, link);
 DoToField(“\pfTEDocument”, 
 (Ptr) &fTEDocument, bObject, link);
 DoToField(“\pfTextView”, 
 (Ptr) &fTextView, bObject, link);
 DoToField(“\pfBox”, (Ptr) &fBox, bObject, link);
 DoToField(“\poldLocation”, 
 (Ptr) &oldLocation, bRect, link);
 DoToField(“\pnewLocation”, 
 (Ptr) &newLocation, bRect, link);
 inherited::Fields(DoToField, link);
}
#endif


#define cDragBox 3001

resource ‘cmnu’ (128) {
 128,
 textMenuProc,
 allEnabled,
 enabled,
 “Buzzwords”,  
 /* these words appear after Undo in the Edit menu */
  {
 “Page Setup Change”, noIcon, noKey, 
 noMark, plain, cChangePrinterStyle;
 “Typing”, noIcon, noKey, noMark, plain, cTyping;
 “Drawing”,  noIcon, noKey, 
 noMark, plain, cDrawBox;
 “Dragging”,  noIcon, noKey, 
 noMark, plain, cDragBox
 }
};

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Ys Chronicles II (Games)
Ys Chronicles II 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: After a hard fight to recover the six sacred books in Ys Chronicles I, Adol is back for a sequel! | Read more »
FINAL FANTASY Ⅸ (Games)
FINAL FANTASY Ⅸ 1.0.4 Device: iOS Universal Category: Games Price: $16.99, Version: 1.0.4 (iTunes) Description: ==========●Special sale price for the FINAL FANTASY IX release! ●20% off from February 10 to February 21, 2016... | Read more »
Tennis Club Story (Games)
Tennis Club Story 1.03 Device: iOS Universal Category: Games Price: $4.99, Version: 1.03 (iTunes) Description: Aim for the ace position of tennis club prestige in this simulation! Your leadership decides if players make it to the big... | Read more »
Juggernaut Wars guide - How to use skill...
Juggernaut Warsis a brand new auto-RPG on iOS and Android that challenges you to build a team of heroes, send them out into various different missions to defeat waves of heroes, and level them up to increase their power. The actual combat itself... | Read more »
Check out the new Pirate Attack update i...
Love pirates and board games? Well, you'll love the new Pirate Attack themed update that just launched in Game of Dice. It adds a bunch of new content themed around pirates, like an all new event map based on a pirate ship which revamps the toll... | Read more »
Splash Cars guide - How to paint the tow...
Splash Cars is an arcade driving game that feels like a hybrid between Dawn of the Plow and Splatoon. In it, you'll need to drive a car around to repaint areas of a town that have lost all of their color. Check out these tips to help you perform... | Read more »
The best video player on mobile
We all know the stock video player on iOS is not particularly convenient, primarily because it asks us to hook a device up to iTunes to sync video in a world that has things like Netflix. [Read more] | Read more »
Four apps to help improve your Super Bow...
Super Bowl Sunday is upon us, and whether you’re a Panthers or a Broncos fan you’re no doubt gearing up for it. [Read more] | Read more »
LooperSonic (Music)
LooperSonic 1.0 Device: iOS Universal Category: Music Price: $4.99, Version: 1.0 (iTunes) Description: LooperSonic is a multi-track audio looper and recorder that will take your loops to the next level. Use it like a loop pedal to... | Read more »
Space Grunts guide - How to survive
Space Grunts is a fast-paced roguelike from popular iOS developer, Orange Pixel. While it taps into many of the typical roguelike sensibilities, you might still find yourself caught out by a few things. We delved further to find you some helpful... | Read more »

Price Scanner via MacPrices.net

What iPad Pro Still Needs To Make It Truly Pr...
I love my iPad Air 2. So much that I’m grudgingly willing to put up with its compromises and limitations as a production tool in order to take advantage of its virtues. However, since a computer for... Read more
21-inch 3.1GHz 4K on sale for $1399, $100 off...
B&H Photo has the 21″ 3.1GHz 4K iMac on sale $1399 for a limited time. Shipping is free, and B&H charges NY sales tax only. Their price is $100 off MSRP: - 21″ 3.1GHz 4K iMac (MK452LL/A): $... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
Save up to $240 with Apple Certified Refurbis...
Apple is now offering Certified Refurbished 12″ Retina MacBooks for up to $240 off the cost of new models. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
Apple refurbished Time Capsules available for...
Apple has certified refurbished Time Capsules available for $120 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $179, $120 off - 3TB... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
Apple has 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.5GHz MacBook Pros... Read more
Apple refurbished 15-inch Retina MacBook Pros...
Apple has Certified Refurbished 2015 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2... Read more
New Liquid Crystal Technology Prevents Automo...
Researchers at the University of Central Florida have developed three new liquid crystal mixtures which will allow automobile displays to operate at unprecedented high and low temperatures In... Read more
BookBook For iPad Pro Coming Soon
The iPad Pro is a device unlike any other, and with Apple Pencil, it’s the ideal portable sketchpad: all that’s missing is the modern easel and portfolio to go. TwelveSouth’s BookBook for iPad Pro... Read more

Jobs Board

Lead Engineer - *Apple* OSX & Hardware...
Lead Engineer - Apple OSX & Hardware **Job ID:** 3125919 **Full/Part\-Time:** Full\-time **Regular/Temporary:** Regular **Listed:** 2016\-02\-10 **Location:** Cary, Read more
*Apple* System Analyst - ATOS IT Services...
Apple System AnalystReference no.198783CountryUSARegionUS - CALIFORNIACityUS - CALIFORNIA - BURBANKPosition TypeProfessionalJob AreaIT SupportJob TypeFull 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
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Subject Matter Expert - Experis (Uni...
This position is for an Apple Subject Matter Expert to assist in developing the architecture, support and services for integration of Apple devices into the domain. Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.