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

Logitech Control Center 3.9.2 - Keyboard...
Logitech Control Center (LCC) is designed to support OS X and allows you to take full advantage of your Logitech keyboard, mouse, or trackball. With the LCC you can: Browse the Internet using... Read more
Adobe Acrobat Pro 15.007.20033 - Powerfu...
Acrobat Pro DC is available only as a part of Adobe Creative Cloud, and can only be installed and/or updated through Adobe's Creative Cloud app. Adobe Acrobat Pro DC with Adobe Document Cloud... Read more
CleanMyMac 3.0.1 - Delete files that was...
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
Evernote 6.0.10 - Create searchable note...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
CleanApp 5.0.1 - Application deinstaller...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
Quicken 2015 2.5.0 - Complete personal f...
Quicken 2015 helps you manage all your personal finances in one place, so you can see where you're spending and where you can save. Quicken automatically categorizes your financial transactions,... Read more
Tonality Pro 1.1.4 - Professional-grade...
Tonality Pro gives you the power to create stunning and dramatic black & white images. This is a complete monochrome image editor with more than 150 one-click style presets, totally unique... Read more
Adobe Photoshop CC 2014 15.2.2 - Profess...
Photoshop CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Photoshop customer). Photoshop CS6 is still available for purchase (... Read more
BBEdit 11.1 - Powerful text and HTML edi...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
Together 3.4.3 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Smart storage. With simple drag-and-drop functionality,... Read more

Play Endless Golf in Flick Golf Free...
Full Fat has released a new update for Flick Golf! Free. The ‘Eliminator’ update brings a whole new way to play with its endless round. [Read more] | Read more »
The Enchanted Cave 2 (Games)
The Enchanted Cave 2 2.1 Device: iOS Universal Category: Games Price: $2.99, Version: 2.1 (iTunes) Description: Delve into a strange cave with a seemingly endless supply of treasure, strategically choosing your battles to gather as... | Read more »
Crystal Siege is on Sale With a New Univ...
Crystal Siege,  FDG Entertainment's RPG  Tower Defense game, has gone universal in its latest update. [Read more] | Read more »
Platforming Action RPG Swordigo is Curre...
Touch Foo's 2D action-platformer, Swordigo, is free for a limited time on the App Store. Now you can run, jump, and slash your way through adventure for absolutely nothing. [Read more] | Read more »
Watch This Homerun Slides into Home on t...
Eyes Wide Games has launched their one-touch baseball game, Watch This Homerun, for the Apple Watch. [Read more] | Read more »
Disney Celebrates May 4th With Galaxy Si...
For Star Wars Day, May 4, join Disney Interactive and Lucasfilm as they celebrate with a whole lot of in=-app sales for their Star Wars apps. [Read more] | Read more »
Oh My Pixel! We Go Hands-on With The Kni...
I recently had a chance to play around with the upcoming Knights of Pen & Paper 2 from Paradox Interactive. I was a huge fan of the first game, so I had a lot of expectations going into it - and I wasn't disappointed. The game has gotten some... | Read more »
Throw Out Your Stylus and Sketch With Pe...
Penpoint Drawing, by Damin Liu,  is a new creative drawing app that uses your finger as your stylus. [Read more] | Read more »
Oceanhouse has Released Just So Thankful...
Oceanhouse Media, makers of digital book apps, are celebrating Mother's Day with a giveaway and a new app. [Read more] | Read more »
Get Dressed, the Virtual Wardrobe App fo...
Dressed, by  Kabuki Vision, is one of the first fashion apps for the Apple Watch. It pairs your watch with your iPhone to let you browse garments from your closet and mix and match them to create the perfect outfit. To add new pieces you just use... | Read more »

Price Scanner via MacPrices.net

12-inch 1.1GHz Silver MacBook in stock today
B&H Photo has the new 12″ 1.1GHz Silver MacBook in stock today for $1299 including free shipping plus NY sales tax only. Act now if you’re interested, since we don’t expect B&H to have this... Read more
iPad Air 2s on sale for up to $50 off, NY tax...
B&H Photo has iPad Air 2s on sale for up to $64 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $469 $30 off - 64GB iPad Air 2 WiFi: $549.99 $50 off - 128GB iPad... Read more
Check Apple prices on any device with the iTr...
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
Sale! New 13-inch 256GB MacBook Air for $1099...
B&H Photo has the new 2015 13″ 1.6GHz/256GB MacBook Air on sale for $1099.99 including free shipping plus NY tax only. Their price is $100 off MSRP. Read more
Japan Post Group, IBM and Apple Deliver iPads...
Japan Post Group, IBM and Apple executives meeting in in New York City yesterday announced a first-of-its-kind initiative aimed at improving the quality of life for millions of Japanese senior... Read more
Worldwide Tablet Market Contracts For Second...
Worldwide tablet shipments recorded a second consecutive quarter of year-over-year decline in the first calendar quarter of 2015 (1Q15), according to preliminary data from the International Data... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz... Read more
13-inch 2.5GHz MacBook Pro available for $999...
Adorama has the 13-inch 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
New 13-inch Retina MacBook Pros available for...
Save up to $80 on the purchase of a new 2015 13″ Retina MacBook Pro at the following resellers. Shipping is free with each model: 2.7GHz/128GB MSRP $1299 2.7GHz/256GB... Read more
13-inch 128GB MacBook Air on sale for $50 off...
Save $50 on the purchase of a new 2015 13″ 1.6GHz/128GB MacBook Air at the following resellers. Shipping is free: $949.99 $949.99 $949.99 $949.99 $949.99 B&H Photo charges NY sales tax only.... Read more

Jobs Board

Senior Identity Architect - *Apple* Pay - A...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with 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
Hardware Systems Integration Engineer - *App...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
Senior Identity Architect - *Apple* Pay - A...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
Hardware Systems Integration Engineer - *App...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.