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

Creative Kit 1.1 - $149.99
Creative Kit 2016--made exclusively for Mac users--is your ticket to the most amazing images you've ever created. With a variety of powerful tools at your fingertips, you'll not only repair and fine-... Read more
iMazing 2.2.3 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Fantastical 2.3.6 - Create calendar even...
Fantastical 2 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
Apple Configurator 2.4 - Configure and d...
Apple Configurator makes it easy to deploy iPad, iPhone, iPod touch, and Apple TV devices in your school or business. Use Apple Configurator to quickly configure large numbers of devices connected to... Read more
WhatRoute 2.0.18 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Fantastical 2.3.6 - Create calendar even...
Fantastical 2 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
Creative Kit 1.1 - $149.99
Creative Kit 2016--made exclusively for Mac users--is your ticket to the most amazing images you've ever created. With a variety of powerful tools at your fingertips, you'll not only repair and fine-... Read more
iMazing 2.2.3 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Apple Configurator 2.4 - Configure and d...
Apple Configurator makes it easy to deploy iPad, iPhone, iPod touch, and Apple TV devices in your school or business. Use Apple Configurator to quickly configure large numbers of devices connected to... Read more
WhatRoute 2.0.18 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more

Power Rangers: Legacy Wars beginner...
Rita Repulsa is back, but this time she's invading your mobile phone in Power Rangers: Legacy Wars. What looks to be a straightforward beat 'em up is actually a tough-as-nails multiplayer strategy game that requires some deft tactical maneuvering.... | Read more »
Hearthstone celebrates the upcoming Jour...
Hearthstone gets a new expansion, Journey to Un'Goro, in a little over a week, and they'll be welcoming the Year of the Mammoth, the next season, at the same time. There's a lot to be excited about, so Blizzard is celebrating in kind. Players will... | Read more »
4 smart and stylish puzzle games like Ty...
TypeShift launched a little over a week ago, offering some puzzling new challenges for word nerds equipped with an iOS device. Created by Zach Gage, the mind behind Spelltower, TypeShift boasts, like its predecessor, a sleak design and some very... | Read more »
The best deals on the App Store this wee...
Deals, deals, deals. We're all about a good bargain here on 148Apps, and luckily this was another fine week in App Store discounts. There's a big board game sale happening right now, and a few fine indies are still discounted through the weekend.... | Read more »
The best new games we played this week
It's been quite the week, but now that all of that business is out of the way, it's time to hunker down with some of the excellent games that were released over the past few days. There's a fair few to help you relax in your down time or if you're... | Read more »
Orphan Black: The Game (Games)
Orphan Black: The Game 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dive into a dark and twisted puzzle-adventure that retells the pivotal events of Orphan Black. | Read more »
The Elder Scrolls: Legends is now availa...
| Read more »
Ticket to Earth beginner's guide: H...
Robot Circus launched Ticket to Earth as part of the App Store's indie games event last week. If you're not quite digging the space operatics Mass Effect: Andromeda is serving up, you'll be pleased to know that there's a surprising alternative on... | Read more »
Leap to victory in Nexx Studios new plat...
You’re always a hop, skip, and a jump away from a fiery death in Temple Jump, a new platformer-cum-endless runner from Nexx Studio. It’s out now on both iOS and Android if you’re an adventurer seeking treasure in a crumbling, pixel-laden temple. | Read more »
Failbetter Games details changes coming...
Sunless Sea, Failbetter Games' dark and gloomy sea explorer, sets sail for the iPad tomorrow. Ahead of the game's launch, Failbetter took to Twitter to discuss what will be different in the mobile version of the game. Many of the changes make... | Read more »

Price Scanner via MacPrices.net

Is A New 10.5-inch iPad Still Coming In April...
There was no sign or mention of a long-rumored and much anticipated 10.5-inch iPad Pro in Apple’s product announcements last week. The exciting iPad news was release of an upgraded iPad Air with a... Read more
T-Mobile’s Premium Device Protection Now Incl...
Good news for T-Mobile customers who love their iPhones and iPads. The “Un-carrier” has become the first national wireless company to give customers AppleCare Services at zero additional cost as part... Read more
FileWave Ensures Support for Latest Apple OS...
FileWave multi-platform device management providers announced support for Apple’s release yesterday of iOS 10.3, macOS Sierra 10.12.4, and tvOS 11.2. FileWave has a history of providing zero-day... Read more
Use Apple’s Education discount to save up to...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more
Apple refurbished Apple Watches available sta...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
9-inch 32GB Space Gray iPad Pro on sale for $...
B&H Photo has the 9.7″ 32GB Space Gray Apple iPad Pro on sale for $549 for a limited time. Shipping is free, and B&H charges NY sales tax only. Their price is $50 off MSRP. Read more
13-inch MacBook Airs on sale for $100-$150 of...
B&H Photo has 13″ MacBook Airs on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/128GB MacBook Air (MMGF2LL/A): $899 $100 off MSRP - 13″ 1.... Read more
13-inch MacBook Airs, Apple refurbished, in s...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.6GHz/8GB/128GB MacBook Air: $... Read more
12-inch Retina MacBooks on sale for $1199, sa...
B&H has 12″ 1.1GHz Retina MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1199 $100 off MSRP - 12″ 1.1GHz... Read more
Save up to $260 with Apple refurbished 12-inc...
Apple has Certified Refurbished 2016 12″ Retina MacBooks available for $200-$260 off MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more

Jobs Board

Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
Desktop Analyst - *Apple* Products - Montef...
…technology to improve patient care. JOB RESPONSIBILITIES: Provide day-to-day support for Apple Hardware and Software in the environment based on the team's support Read more
*Apple* Mobile Master - Best Buy (United Sta...
**493168BR** **Job Title:** Apple Mobile Master **Location Number:** 000827-Denton-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** At Read more
Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492889BR** **Job Title:** Apple Mobile Master **Location Number:** 000886-Norwalk-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.