Related Info: Quickdraw

C++ Object Lists

By Jörg Langowski, MacTutor Editorial Board

“C++ object lists in windows”

Our third example application in C++ deals with another common aspect of Macintosh programming: Documents that have several objects associated and on which some action has to be performed. One of the best known examples would be a MacDraw document, where a document can contain (almost) any number of lines, polygons, rectangles, etc. All these objects have to be drawn when the window is updated, have to be moved or changed otherwise when the mouse is clicked on them, etc.

The classical example of late binding in object-oriented programming is, in fact, just this type of program: a window is created that contains a number of objects. We don’t know which type of objects or how many the window will contain at run time; all we know is that they must be drawn somehow.

Linked lists and late binding

For this type of problem, one usually creates a linked list of objects which is associated with the window. New objects can be added to or removed from the list. Drawing the contents of the window simply means traversing the list from beginning to end and drawing every object that is found. And here run-time binding comes in: since we don’t know the exact type of the object myObj that we’ll find at any particular place in the list, we’ll simply write Draw->myObj and let the run time code decide which particular drawing method should be used.

The example is illustrated by a piece of code from listing 2:

// 1

void TListDoc::DrawWindow(void)
{TObjLink* temp;
 SetPort(fDocWindow);
 EraseRect(&fDocWindow->portRect);
 if (fObjList->NumObjs() != 0)
 for (temp = fObjList->Header(); 
 temp != nil; temp = temp->GetNext())
 { SysBeep(1);  // to let something happen
 temp->GetmyObj()->Draw(qd.gray);  }
} // DrawWindow

TListDoc (listing 2) is our document class, the window that contains the objects to be drawn. These objects are contained in a list fObjList of type TObjList (listing 3), which consists of list elements of type TObjLink. Each list element is an object that contains two instance variables: a pointer to the next element in the list, fNext, and a pointer to the element’s contents fmyObj. In our case, fmyObj is an object of type TDisplObj, with the subclasses TRect, TOval, and TRoundRect. Fig. 1 shows its structure.

Fig. 1: structure of the TObjList class

The contents of a list element are not accessible directly, and the public function GetMyObj() is provided for returning a pointer to the object referred to by a particular list element.

List elements can be easily inserted into and removed from structures such as TObjList by simply changing the fNext pointers. The AddObj and RemoveObj functions are provided for this purpose. The list is linear, only one link per list element is defined. If one wanted to create branched lists like those in Lisp, one would have to define two links, both of which might alternatively point to other list elements or to simple objects (‘atoms’). This is not what we want for our list of display objects, which will just be traversed from beginning to end; thus we create a simple linear list.

Traversing the list is achieved by the for() statement at the end of the function definition; the variable temp contains a pointer to successive list elements, and the end is reached when a list element has no successor (GetNext() returns nil). Each list element’s “draw object” is then drawn using temp->GetmyObj()->Draw(qd.gray). This assumes that the object returned by GetMyObj() has a Draw method; the generic object class TListObj must have such a method defined as virtual for implementation in one of the subclasses. If the subclass does not define Draw(), the parent class’ Draw() is called, causing an error message.

The objects that may be drawn have a fixed location in the window; they are defined in the TListDoc initializer and are added to or removed from each document’s display list according to choices from a three-item menu. The menu item strings are adjusted depending on whether the object can be added or removed.

In a ‘real’ application, you would add a DoContent() method to the definition of a display object which allows some specific behavior when the mouse is clicked inside the object’s rectangle. This method would be invoked from the document’s DoContent() method; one would traverse the display list as before, check which object, if any, the mouse is clicked in, and call its DoContent() method.

I have also provided a virtual DoIdle() method which you may call for periodic actions inside one of the objects, for instance a clock display or some blinking text.

You should run the application and watch its behavior closely; note in particular that the order in which the three objects are drawn is different depending on the order in which the menu items were initially selected. This is plausible, because the objects are inserted into the list one before the other, and later drawn in the same order (last inserted, first drawn). Note also that update events are generated for the partially visible windows and that a beep accompanies the drawing of each object, even if that drawing takes place in a hidden part of a window and is therefore clipped.

Miscellaneous

We have now seen three examples of small Macintosh applications built around the application framework provided with the MPW C++ environment. Although this application framework is not MacApp, it implements a great deal of the basic functionality of a typical Macintosh application, and I like it for its simplicity. I was almost tempted to write ‘simplicity and speed’ there, but compiling this month’s example still takes me 3-5 minutes every time I make a change. MacApp might be still slower, but I’ll look into that in one of my next columns. The C++ environment allows working with the MacApp libraries, all the necessary header files are provided; so far I haven’t taken a closer look, but that will come soon.

[For fast compiling, one thing that Apple recommends is to include only the header files absolutely necessary for a piece of code, and control those includes through the use of compile-time variables, such as

Still, C++ is a change for someone used to the speed of a ‘compile-and-go’ environment like Mach2; I suppose when you give up a lot of the important features of C++, Think C 4.0 will allow you to do object-oriented programming in C with much shorter cycle times. A comparison of the relative merits of Think’s Object C and MPW C++ will follow in one of the next columns.

Also to follow: some more recent changes to the C++ definitions laid out in Stroustrup’s first book, ‘The C++ Programming Language’. The change from C++ 1.0 to C++ 2.0 included, among other things, the addition of protected fields to classes, and multiple inheritance. So far we have used mainly features that were already defined in C++ 1.0 (we did use protected fields, however). The next column will give some examples of the more advanced features.

At last, I have to apologize for a bug that was still present in my last example: when you tried to use the scroll bars’ arrows or page regions, the scroll bars would scroll with the rest of the window and thus disappear from underneath the mouse pointer! That can be funny to watch, but is not really what we want in an application. The reason was that I called SetOrigin too early, namely from within the control action procedure. So, to fix that bug, all you have to do is: 1. remove the calls to SetOrigin from the control action procedures HActionProc and VActionProc; 2. change the code after default: near the end of the definition of TMacTutorGrow:DoContent to:

//2

if ( control == fDocVScroll )
{
 value -= TrackControl(control, mouse, 
 (ProcPtr) VActionProc);
 SetOrigin(tRect.left,tRect.top-value);
}
else 
{
 value -= TrackControl(control, mouse,
 (ProcPtr) HActionProc);
 SetOrigin(tRect.left-value,tRect.top);
}
AdjustScrollSizes();
break;

and your scroll bars should work (approximately) correctly.

Listing 1: 


/*--------------------------------------------------
#DocListApp
#
#Examples for object lists associated with windows
#J. Langowski / MacTutor 1989
#----------------------------------------------------  */
#include <Types.h>
#include <QuickDraw.h>
#include <Fonts.h>
#include <Events.h>
#include <OSEvents.h>
#include <Controls.h>
#include <Windows.h>
#include <Menus.h>
#include <TextEdit.h>
#include <Dialogs.h>
#include <Desk.h>
#include <Scrap.h>
#include <ToolUtils.h>
#include <Memory.h>
#include <SegLoad.h>
#include <Files.h>
#include <OSUtils.h>
#include <Traps.h>
#include <StdLib.h>
#include “TDocument.h”
#include “TApplication.h”
#include “DocListApp.h”
#include “DisplList.h”
#include “ListDoc.h”

// Methods for our application class
// a few of them taken ‘as is’ from Apple’s example
// (see previous two columns)

TDocListApp::TDocListApp(void)
{
 Handle menuBar;

 // read menus into menu bar
 menuBar = GetNewMBar(rMenuBar);
 // install menus
 SetMenuBar(menuBar);
 DisposHandle(menuBar);
 // add DA names to Apple menu
 AddResMenu(GetMHandle(mApple), ‘DRVR’);
 DrawMenuBar();
 // create empty mouse region
 fMouseRgn = NewRgn();
 // create a single empty document
 DoNew();
}

// Tell TApplication class how much heap we need
long TDocListApp::HeapNeeded(void)
{return (kMinSize * 1024);}

unsigned long TDocListApp::SleepVal(void)
{
 unsigned long sleep;
 const long kSleepTime = 0x7fffffff; 
 sleep = kSleepTime;
 if ((!fInBackground))
 { sleep = GetCaretTime();}
 return sleep;
}

void TDocListApp::AdjustMenus(void)
{
 WindowPtrfrontmost;
 MenuHandle menu;
 Boolean undo,cutCopyClear,paste;

 TListDoc* fCurListDoc = (TListDoc*) fCurDoc;

 frontmost = FrontWindow();

 menu = GetMHandle(mFile);
 if ( fDocList->NumDocs() < kMaxOpenDocuments )
   EnableItem(menu, iNew);
   // New is enabled when we can open more documents 
 else DisableItem(menu, iNew);
 if ( frontmost != (WindowPtr) nil )
   EnableItem(menu, iClose);
   // Close is enabled when there is a window to close 
 else DisableItem(menu, iClose);

 undo = false; cutCopyClear = false; paste = false;
 
 if ( fCurListDoc == nil )
   {  // all editing is enabled for DA windows 
 undo = true;  cutCopyClear = true;
 paste = true;  }
   
 menu = GetMHandle(mEdit);
 if ( undo )EnableItem(menu, iUndo);
 else   DisableItem(menu, iUndo);
 
 if ( cutCopyClear )
   {  EnableItem(menu, iCut);
 EnableItem(menu, iCopy);
 EnableItem(menu, iClear);} 
 else
   {  DisableItem(menu, iCut);
 DisableItem(menu, iCopy);
 DisableItem(menu, iClear); }
   
 if ( paste )  EnableItem(menu, iPaste);
 else   DisableItem(menu, iPaste);
 
 menu = GetMHandle(myMenu);
 EnableItem(menu, item1); EnableItem(menu, item2);
 EnableItem(menu, item3);
 if (fCurListDoc->fItem1Set)
 SetItem(GetMHandle(myMenu),item1, “\pRoundRect-”);
 else SetItem(GetMHandle(myMenu),item1, “\pRoundRect+”);
 if (fCurListDoc->fItem2Set)
 SetItem(GetMHandle(myMenu),item2, “\pOval-”);
 else SetItem(GetMHandle(myMenu),item2, “\pOval+”);
 if (fCurListDoc->fItem3Set)
 SetItem(GetMHandle(myMenu),item3, “\pRect-”);
 else SetItem(GetMHandle(myMenu),item3, “\pRect+”);
} // AdjustMenus

void TDocListApp::DoMenuCommand(short menuID, short menuItem)
{short  itemHit; Str255 daName;
 short  daRefNum;WindowPtrwindow;
 TListDoc* fCurListDoc = (TListDoc*) fCurDoc;

 window = FrontWindow();
 switch ( menuID )
   {  case mApple:
 switch ( menuItem )
   {  case iAbout: // About box
 itemHit = Alert(rAboutAlert, nil);
 break;
 default: // DAs etc.
 GetItem(GetMHandle(mApple), menuItem, daName);
 daRefNum = OpenDeskAcc(daName);
 break; }
 break;
 case mFile:
 switch ( menuItem )
   {  case iNew: DoNew(); break;
 case iClose:
 if (fCurListDoc != nil)
   {  fDocList->RemoveDoc (fCurListDoc);
 delete fCurListDoc; }
 else CloseDeskAcc(((WindowPeek)
 fWhichWindow)->windowKind);
 break;
 case iQuit:Terminate();  break; }
 break;
 case mEdit:
 // call SystemEdit for DA editing & MultiFinder 
 if ( !SystemEdit(menuItem-1) )
   {  switch ( menuItem )
   {  case iCut: break;
 case iCopy: break;
 case iPaste: break;
 case iClear: break; }
   }
 break;
 case myMenu:
 if (fCurListDoc != nil) 
 { switch ( menuItem )
   {  case item1:
 if (fCurListDoc->fItem1Set)
fCurListDoc->fObjList->RemoveObj(fCurListDoc->obj1);
 else
fCurListDoc->fObjList->AddObj(fCurListDoc->obj1);
 fCurListDoc->fItem1Set = !fCurListDoc->fItem1Set;
 break;
 case item2:
 if (fCurListDoc->fItem2Set)
fCurListDoc->fObjList->RemoveObj(fCurListDoc->obj2);
 else
fCurListDoc->fObjList->AddObj(fCurListDoc->obj2);
 fCurListDoc->fItem2Set = !fCurListDoc->fItem2Set;
 break;
 case item3: 
 if (fCurListDoc->fItem3Set)
fCurListDoc->fObjList->RemoveObj(fCurListDoc->obj3);
 else
fCurListDoc->fObjList->AddObj(fCurListDoc->obj3);
 fCurListDoc->fItem3Set = !fCurListDoc->fItem3Set;
 break; }

 InvalRect(&(window->portRect));
 fCurListDoc->DoUpdate(); }
 break; }
 HiliteMenu(0);  } // DoMenuCommand

void TDocListApp::DoNew(void)
{TListDoc* tMyDoc;
 
 tMyDoc = new TListDoc(rDocWindow);
 if (tMyDoc != nil) fDocList->AddDoc(tMyDoc);
} // DoNew

void TDocListApp::Terminate(void)
{ExitLoop();} // Terminate

TDocListApp *gTheApplication;

int main(void)
{gTheApplication = new TDocListApp;
 if (gTheApplication == nil) return 0;
 gTheApplication->EventLoop();
 return 0;}

Listing 2: ListDoc.cp

#include <Types.h>
#include <QuickDraw.h>
#include <Fonts.h>
#include <Events.h>
#include <Controls.h>
#include <Windows.h>
#include <Menus.h>
#include <TextEdit.h>
#include <Dialogs.h>
#include <Desk.h>
#include <Scrap.h>
#include <ToolUtils.h>
#include <Memory.h>
#include <SegLoad.h>
#include <Files.h>
#include <OSUtils.h>
#include <Traps.h>
#include <StdLib.h>
#include “TDocument.h”
#include “DisplList.h”
#include “ListDoc.h”

// create and delete the document window
TListDoc::TListDoc(short resID) : (resID)
{Rect brect;
 fItem1Set = fItem2Set = fItem3Set = false;
 SetRect(&brect,10,100,70,140);
 obj1 = new TRoundRect(brect);
 SetRect(&brect,90,100,150,140);
 obj2 = new TOval(brect);
 SetRect(&brect,170,100,230,140);
 obj3 = new TRect(brect);
 fObjList = new TObjList();
 ShowWindow(fDocWindow);  }

TListDoc::~TListDoc(void)
{delete fObjList;
 HideWindow(fDocWindow);  }

void TListDoc::DoUpdate(void)
{BeginUpdate(fDocWindow); 
 if ( ! EmptyRgn(fDocWindow->visRgn) ) 
   {  DrawWindow();}
 EndUpdate(fDocWindow);   }

// Draw all objects contained in the list. 
void TListDoc::DrawWindow(void)
{TObjLink* temp;
 SetPort(fDocWindow);
 EraseRect(&fDocWindow->portRect);
 if (fObjList->NumObjs() != 0)
 for (temp = fObjList->Header(); 
 temp != nil; temp = temp->GetNext())
 { SysBeep(1);  // to let something happen
 temp->GetmyObj()->Draw(qd.gray);  }
} // DrawWindow

Listing 3: DisplList.cp

#include <Types.h>
#include <QuickDraw.h>
#include <Events.h>
#include <StdLib.h>
#include “DisplList.h”

TObjLink::TObjLink(TObjLink *n, TDisplObj *v)
{fNext = n; fmyObj = v;   }

TObjList::TObjList(void)
{fHeader = nil; fNumObjs = 0; }

void TObjList::AddObj(TDisplObj* obj)
{if (obj != nil)
 { TObjLink* temp;
 temp = new TObjLink(fHeader,obj);
 fHeader = temp;
 fNumObjs++;}
}

void TObjList::RemoveObj(TDisplObj* obj)
{if (obj != nil)
 { TObjLink* temp;
 TObjLink* last;
 last = nil;
 for (temp = fHeader; temp != nil; 
 temp = temp->GetNext())
   if (temp->GetmyObj() == obj)
 {  if (last == nil) 
 // if first item in list, just set first
 fHeader = temp->GetNext();
   else last->SetNext(temp->GetNext());
   delete temp;  // free the TObjLink
   fNumObjs--;   return;  }
   else last = temp; }
}

TDisplObj::TDisplObj(Rect r)  { fBoundRect = r; }

TRoundRect::TRoundRect(Rect r) : (r)
 // Calls base class constructor
{fOvalWidth = 20;
 fOvalHeight = 15; }

void TRoundRect::Draw(Pattern pat)
{PenNormal();
 FillRoundRect(&fBoundRect, fOvalWidth, fOvalHeight, pat);
 FrameRoundRect(&fBoundRect, fOvalWidth, fOvalHeight);   }

void TRoundRect::Erase()
{EraseRoundRect(&fBoundRect, fOvalWidth, fOvalHeight);   }

TRect::TRect(Rect r) : (r) {}

void TRect::Draw(Pattern pat)
{PenNormal();
 FillRect(&fBoundRect, pat);
 FrameRect(&fBoundRect);  }

void TRect::Erase()
{EraseRect(&fBoundRect);  }

TOval::TOval(Rect r) : (r) {}

void TOval::Draw(Pattern pat)
{PenNormal();
 FillOval(&fBoundRect, pat);
 FrameOval(&fBoundRect);  }

void TOval::Erase()
{EraseOval(&fBoundRect);  }

Listing 4: Header Files

DocListApp.h

// Constants, resource definitions, etc.
 // basically the same as in last month’s example
#define kErrStrings 129

/* The following are indicies into STR# resources. */
#define eNoMemory1
#define eNoWindow2

#define kMinSize 48 // min heap needed in K

#define rMenuBar 128 /* application’s menu bar */
#define rAboutAlert128  /* about alert */
#define rDocWindow 128  /* application’s window */

#define mApple 128 /* Apple menu */
#define iAbout 1
#define mFile  129 /* File menu */
#define iNew1
#define iClose 4
#define iQuit  12
#define mEdit  130 /* Edit menu */
#define iUndo  1
#define iCut3
#define iCopy  4
#define iPaste 5
#define iClear 6
#define myMenu 131   /* Sample menu */
#define item1  1
#define item2  2
#define item3  3

class TDocListApp : public TApplication {
public:
 TDocListApp(void);// Our constructor
private:
 // routines from TApplication we are overriding
 long HeapNeeded(void);
 unsigned long SleepVal(void);
 void AdjustMenus(void);
 void DoMenuCommand(short menuID, short menuItem);
 // our own routines
 void DoNew(void);
 void Terminate(void);
};

const short kMaxOpenDocuments = 4;

ListDoc.h

// List document class
//
class TListDoc : public TDocument {
  protected:
 void DrawWindow(void);
 public:
   Boolean fItem1Set,fItem2Set,fItem3Set;
 TDisplObj  *obj1,*obj2,*obj3;
 TObjList*fObjList;// list of objects to be drawn
 TListDoc(short resID);
 ~TListDoc(void);
 
 // methods from TDocument we override
 void DoUpdate(void);
};

const int kMinDocDim = 40;

DisplList.h

class TDisplObj {
  public:
 virtual void Draw(Pattern) 
 {DebugStr(“\pCall to TDisplObj::Draw”);}
 virtual void Erase()  
 {DebugStr(“\pCall to TDisplObj::Erase”);}
 virtual void DoContent()
 {DebugStr(“\pCall to TDisplObj::DoContent”);}
 virtual void DoIdle() { /* do nothing by default*/ }
  protected:
 // Only accessible to public descendants
 TDisplObj(Rect r);
 Rect fBoundRect;
  private:
 Boolean HiLiteState;// true : highlighted
};
class TObjLink {
 friend class TObjList;
  // TObjList may access our private members
 TObjLink*fNext; // the link to the next object
 TDisplObj* fmyObj;// the object this link refers to
 // our constructor can take args for convenience;
 // they default to nil.
 TObjLink(TObjLink *n = nil, TDisplObj *v = nil);
  public:
 inline TObjLink*GetNext() { return fNext; };
 inline TDisplObj* GetmyObj() { return fmyObj; };
 inline voidSetNext(TObjLink* aLink) { fNext = aLink; };
 inline void   SetmyObj(TDisplObj* aObj) { fmyObj = aObj; };
};
class TObjList {
 TObjLink*fHeader; // the first link in our list
 int  fNumObjs;  // the number of elements in the list
public:
 TObjList(void); // our constructor
 inline TObjLink* Header() { return fHeader; }
 inline int NumObjs() { return fNumObjs; }
 void AddObj(TDisplObj* obj);
 void RemoveObj(TDisplObj* obj);
};
class TRoundRect : public TDisplObj {
  public:
 TRoundRect(Rect r);
 virtual void Draw(Pattern);
 virtual void Erase();
  private:
 short fOvalWidth, fOvalHeight;
 // curvature of rounded corners 
};
class TOval : public TDisplObj {
  public:
 TOval(Rect r);
 virtual void Draw(Pattern);
 virtual void Erase();
};
class TRect : public TDisplObj {
  public:
 TRect(Rect r);
 virtual void Draw(Pattern);
 virtual void Erase();
};