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

Ableton Live 10.1.1 - 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
BetterTouchTool 3.202 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom)... Read more
Fission 2.4.6 - Streamlined audio editor...
Fission can crop and trim audio, paste in or join files, or just rapidly split one long file into many. It's streamlined for fast editing. Plus, it works without the quality loss caused by other... Read more
Drama 1.0.27 - Prototyping, animation...
Drama's handy 3-in-1 functionality uniquely integrates design, animation and prototyping into a single familiar tool. No more frustrating switching between apps or learning new stuff. And by... Read more
Adobe Lightroom Classic CC 8.4.1 - Impor...
Adobe Lightroom Classic is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Adobe Lightroom Classic CC (was Adobe... Read more
iExplorer 4.3.2 - View and transfer file...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
Adobe After Effects CC 2018 16.1.3 - Cre...
After Effects CC 2018 is available as part of Adobe Creative Cloud for $52.99/month (or $20.99/month for a single app license). The new, more connected After Effects CC 2018 can make the impossible... Read more
Adobe Audition CC 2019 12.1.4 - Professi...
Audition CC 2019 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Audition customer). Adobe Audition CC 2019 empowers you to create and... Read more
Adobe Premiere Pro CC 2019 13.1.5 - Digi...
Premiere Pro CC 2019 is available as part of Adobe Creative Cloud for as little as $52.99/month. The price on display is a price for annual by-monthly plan for Adobe Premiere Pro only Adobe Premiere... Read more
Navicat Premium Essentials 12.1.25 - Pro...
Navicat Premium Essentials is a compact version of Navicat which provides basic and necessary features you will need to perform simple administration on a database. It supports the latest features... Read more

Latest Forum Discussions

See All

Marvel Strike Force is adding Agent Coul...
Marvel Strike Force, the popular squad-based RPG, is set to receive a bunch of new content over the next few weeks. [Read more] | Read more »
Lots of premium games are going free (so...
You may have seen over the past couple weeks a that a bunch of premium games have suddenly become free. This isn’t a mistake, nor is it some last hurrah before Apple Arcade hits, and it’s important to know that these games aren’t actually becoming... | Read more »
Yoozoo Games launches Saint Seiya Awaken...
If you’re into your anime, you’ve probably seen or heard of Saint Seiya. Based on a shonen manga by Masami Kurumada, the series was massively popular in the 1980s – especially in its native Japan. Since then, it’s grown into a franchise of all... | Read more »
Five Nights at Freddy's AR: Special...
Five Nights at Freddy's AR: Special Delivery is a terrifying new nightmare from developer Illumix. Last week, FNAF fans were sent into a frenzy by a short teaser for what we now know to be Special Delivery. Those in the comments were quick to... | Read more »
Rush Rally 3's new live events are...
Last week, Rush Rally 3 got updated with live events, and it’s one of the best things to happen to racing games on mobile. Prior to this update, the game already had multiplayer, but live events are more convenient in the sense that it’s somewhat... | Read more »
Why your free-to-play racer sucks
It’s been this way for a while now, but playing Hot Wheels Infinite Loop really highlights a big issue with free-to-play mobile racing games: They suck. It doesn’t matter if you’re trying going for realism, cart racing, or arcade nonsense, they’re... | Read more »
Steam Link Spotlight - The Banner Saga 3
Steam Link Spotlight is a new feature where we take a look at PC games that play exceptionally well using the Steam Link app. Our last entry talked about Terry Cavanaugh’s incredible Dicey Dungeons. Read about how it’s a great mobile experience... | Read more »
Combo Quest (Games)
Combo Quest 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Combo Quest is an epic, time tap role-playing adventure. In this unique masterpiece, you are a knight on a heroic quest to retrieve... | Read more »
Hero Emblems (Games)
Hero Emblems 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ** 25% OFF for a limited time to celebrate the release ** ** Note for iPhone 6 user: If it doesn't run fullscreen on your device... | Read more »
Puzzle Blitz (Games)
Puzzle Blitz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Puzzle Blitz is a frantic puzzle solving race against the clock! Solve as many puzzles as you can, before time runs out! You have... | Read more »

Price Scanner via MacPrices.net

4-core and 6-core 2018 Mac minis available at...
Apple has Certified Refurbished 2018 Mac minis available on their online store for $120-$170 off the cost of new models. Each mini comes with a new outer case plus a standard Apple one-year warranty... Read more
$250 prepaid Visa card with any Apple iPhone,...
Xfinity Mobile will include a free $250 prepaid Visa card with the purchase of any new iPhone, new line activation, and transfer of phone number to Xfinity Mobile. Offer is valid through October 27,... Read more
Sprint is offering the 64GB Apple iPhone 11 P...
Sprint has the new 64GB iPhone 11 Pro available for $12.50 per month for new customers with an eligible trade-in in of iPhone 7 or newer. That’s down from their standard monthly lease of $41.67. The... Read more
Final week: Apple’s 2019 Back to School Promo...
Purchase a new Mac using Apple’s Education discount, and take up to $400 off MSRP. All teachers, students, and staff of any educational institution with a .edu email address qualify for the discount... Read more
Save $30 on Apple’s AirPods at these reseller...
Amazon is offering discounts on new 2019 Apple AirPods ranging up to $30 off MSRP as part of their Labor Day sale. Shipping is free: – AirPods with Charging Case: $144.95 $15 off MSRP – AirPods with... Read more
Preorder your Apple Watch Series 5 today at A...
Amazon has Apple Watch Series 5 GPS models available for preorder and on sale today for $15 off Apple’s MSRP. Shipping is free and starts on September 20th: – 40mm Apple Watch Series 5 GPS: $384.99 $... Read more
21″ iMacs on sale for $100 off Apple’s MSRP,...
B&H Photo has new 21″ Apple iMacs on sale for $100 off MSRP with models available starting at $999. These are the same iMacs offered by Apple in their retail and online stores. Overnight shipping... Read more
2018 4 and 6-Core Mac minis on sale today for...
Apple resellers are offering new 2018 4-Core and 6-Core Mac minis for $100-$150 off MSRP for a limited time. B&H Photo has the new 2018 4-Core and 6-Core Mac minis on sale for up to $150 off... Read more
Save $150-$250 on 10.2″ WiFi + Cellular iPads...
Verizon is offering $150-$250 discounts on Apple’s new 10.2″ WiFi + Cellular iPad with service. Buy the iPad itself and save $150. Save $250 on the purchase of an iPad along with an iPhone. The fine... Read more
Apple continues to offer 13″ 2.3GHz Dual-Core...
Apple has Certified Refurbished 2017 13″ 2.3GHz Dual-Core non-Touch Bar MacBook Pros available starting at $1019. An standard Apple one-year warranty is included with each model, outer cases are new... Read more

Jobs Board

*Apple* Mobility Pro - Best Buy (United Stat...
**719499BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Location Number:** 001266-Charleston-Store **Job Description:** At Best Buy, our Read more
Best Buy *Apple* Computing Master - Best Bu...
**733266BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000144-Union City-Store **Job Description:** **What does a Read more
Best Buy *Apple* Computing Master - Best Bu...
**730765BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000565-St Petersburg-Store **Job Description:** **What does Read more
*Apple* Mobile Master - Best Buy (United Sta...
**725617BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 001095-Chesterfield-Store **Job Description:** **What does a Read more
Student Employment (Blue *Apple* Cafe) Spri...
Student Employment (Blue Apple Cafe) Spring 2019 Penn State University Campus/Location: Penn State Brandywine Campus City: Media, PA Date Announced: 12/20/2018 Date Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.