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

Tidy Up 5.3.7 - Find duplicate files and...
Tidy Up is a full-featured duplicate finder and disk-tidiness utility. Features: Supports Lightroom: it is now possible to search and collect duplicates directly in the Lightroom library. Multiple... Read more
Pinegrow 5.97 - Mockup and design web pa...
Pinegrow (was Pinegrow Web Designer) is desktop app that lets you mockup and design webpages faster with multi-page editing, CSS and LESS styling, and smart components for Bootstrap, Foundation,... Read more
BlueStacks 4.210.0 - Run Android applica...
BlueStacks App Player lets you run your Android apps fast and fullscreen on your Mac. Feature comparison chart How to install Bluestacks on your Mac Go to MacUpdate and click the green "Download"... Read more
WhatsApp 2.2027.10 - Desktop client for...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
Art Text 4.0.1 - $29.99
Art Text is graphic design software specifically tuned for lettering, typography, text mockups and various artistic text effects. Supplied with a great variety of ready to use styles and materials,... Read more
Adobe Dreamweaver CC 2020 20.2 - Build w...
Dreamweaver CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2020 allows you to... Read more
Adobe Acrobat DC 20.009.20074 - Powerful...
Acrobat 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 DC with Adobe Document Cloud services is... Read more
beaTunes 5.2.10 - Organize your music co...
beaTunes is a full-featured music player and organizational tool for music collections. How well organized is your music library? Are your artists always spelled the same way? Any R.E.M. vs REM?... Read more
DiskCatalogMaker 8.1.5 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Meteorologist 3.4.1 - Popular weather ap...
Meteorologist is a simple interface to weather provided by weather.com. It provides the ability to show the weather in the main menu bar, displaying more detail in a pop-up menu, whose contents are... Read more

Latest Forum Discussions

See All

Steam Link Spotlight - Disco Elysium
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry was Signs of the Sojourner Read about how it plays using Steam Link over here. | Read more »
Distract Yourself With These Great Mobil...
There’s a lot going on right now, and I don’t really feel like trying to write some kind of pithy intro for it. All I’ll say is lots of people have been coming together and helping each other in small ways, and I’m choosing to focus on that as I... | Read more »
Pokemon Go's July Community Day wil...
Pokemon Go developers have announced the details concerning the upcoming Gastly Community Day. This particular event was selected by the players of the game after the Gas Pokemon came in second place after a poll that decided which Pokemon would... | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Detective Di is a point-and-click murder...
Detective Di is a point-and-click murder mystery set in Tang Dynasty-era China. You'll take on the role of China's best-known investigator, Di Renjie, as he solves a series of grisly murders that will ultimately lead him on a collision course with... | Read more »
Dissidia Final Fantasy Opera Omnia is se...
Dissidia Final Fantasy Opera Omnia, one of Square Enix's many popular mobile RPGs, has announced a plethora of in-game events that are set to take place over the summer. This will include several rewards, Free Multi Draws and more. [Read more] | Read more »
Sphaze is a neat-looking puzzler where y...
Sphaze is a neat-looking puzzler where you'll work to guide robots through increasingly elaborate mazes. It's set in a visually distinct world that's equal parts fantasy and sci-fi, and it's finally launched today for iOS and Android devices. [... | Read more »
Apple Arcade is in trouble
Yesterday, Bloomberg reported that Apple is disappointed in the performance of Apple Arcade and will be shifting their approach to the service by focusing on games that can retain subscribers and canceling other upcoming releases that don't fit... | Read more »
Pixel Petz, an inventive platform for de...
Pixel Petz has built up a sizeable player base thanks to its layered, easy-to-understand creative tools and friendly social experience. It revolves around designing, trading, and playing with a unique collection of pixel art pets, and it's out now... | Read more »
The King of Fighters Allstar's late...
The King of Fighters ALLSTAR, Netmarble's popular action RPG, has once again been updated with a plethora of new content. This includes battle cards, events and 21 new fighters, which increases the already sizeable roster even more. [Read more] | Read more »

Price Scanner via MacPrices.net

Clearance 2019 13″ 2.4GHz/256GB MacBook Pro o...
B&H Photo has dropped their price on the clearance 2019 13″ 2.4GHz/256GB Quad-Core Silver MacBook Pro by $500 off Apple’s original MSRP to a new low of only $1299. Expedited shipping is free to... Read more
$219 Apple AirPods Pro are back at Verizon, s...
Verizon has Apple AirPods Pro on sale again for a limited time for $219.99 on their online store. Their price is $30 off Apple’s MSRP, and it’s the lowest price we’ve seen for AirPods Pro. Available... Read more
Apple’s $779 13″ MacBook Air deal returns to...
Apple has clearance, Certified Refurbished, 2019 13″ MacBook Airs available again starting at $779. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is... Read more
$200 13″ MacBook Pro discounts are back at Am...
Amazon has 2020 13″ 2.0GHz MacBook Pros on sale again today for $150-$200 off Apple’s MSRP. Shipping is free. Be sure to purchase the MacBook Pro from Amazon, rather than a third-party seller, and... Read more
Deal Alert! Apple AirPods with Wireless Charg...
Sams Club has Apple AirPods with Wireless Charging Case on sale on their online store for only $149.98 from July 6, 2020 to July 9, 2020. Their price is $50 off Apple’s MSRP, and it’s the lowest... Read more
Xfinity Mobile promo: Apple iPhone XS models...
Take $300 off the purchase of any Apple iPhone XS model at Xfinity Mobile while supplies last. Service plan required: – 64GB iPhone XS: $599.99 save $300 – 256GB iPhone XS: $749.99 save $300 – 512GB... Read more
New July 2020 promo at US Cellular: Switch an...
US Cellular has introduced a new July 2020 deal offering free 64GB Apple iPhone 11 smartphones to customers opening a new line of service. No trade-in required, and discounts are applied via monthly... Read more
Apple offers up to $400 Education discount on...
Apple has launched their Back to School promotion for 2020. They will include one free pair Apple AirPods (with charging case) with the purchase of a MacBook Air, MacBook Pro, iMac, or iMac Pro (Mac... Read more
July 4th Sale: Woot offers wide range of Macs...
Amazon-owned Woot is blowing out a wide range of Apple Macs and iPads for July 4th staring at $279 and ranging up to just over $1000. Models vary from older iPads and 11″ MacBook Airs to some newer... Read more
Apple Pro Display XDR with Nano-Texture Glass...
Abt Electronics has Apple’s new 32″ Pro Display XDR model with the nano-texture glass in stock and on sale today for up to $144 off MSRP. Shipping is free: – Pro Display XDR (nano-texture glass): $... Read more

Jobs Board

Physical Therapist Assistant - *Apple* Hill...
Physical Therapist Assistant - Apple Hill Rehab - Full Time Tracking Code 62519 Job Description General Summary: Under the direct supervision of a licensed Physical Read more
Operating Room Assistant, *Apple* Hill Surg...
Operating Room Assistant, Apple Hill Surgical Center - Full Time, Day Shift, Monday - Saturday availability required Tracking Code 62363 Job Description Operating Read more
Perioperative RN - ( *Apple* Hill Surgical C...
Perioperative RN - ( Apple Hill Surgical Center) Tracking Code 60593 Job Description Monday - Friday - Full Time Days Possible Saturdays General Summary: Under the Read more
Product Manager, *Apple* Commercial Sales -...
Product Manager, Apple Commercial Sales Austin, TX, US Requisition Number:77652 As an Apple Product Manager for the Commercial Sales team at Insight, you Read more
*Apple* Mac Product Engineer - Barclays (Uni...
Apple Mac EngineerWhippany, NJ Support the development and delivery of solutions, products, and capabilities into the Barclays environment working across technical Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.