Sample App in C++
Volume Number: | | 5
|
Issue Number: | | 12
|
Column Tag: | | Jörg's Folder
|
C++ Sample Application
By Jörg Langowski, MacTutor Editorial Board
Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.
C++ Sample Application
As I am writing this, MPW C++ is shipping; version 3.1b1 is available through APDA as of October 11. The following message could be found on Applelink:
On Tuesday, October 3, 1989 Apple Computer, Inc announced MPW C++ v.3.1B1 and said MPW C++ was available for ordering immediately and would be shipping later in October. Later is here NOW! MPW C++ v.3.1B1 started shipping on Wednesday, October 11, 1989!
To get your copy, call APDA at
1-800-282-2732 (U.S.)
1-800-637-0029 (Canada)
1-408-562-3910 (International)
ask for part number M0346LL/A. The price is $175 and the package includes one Apple C++ Manual, three AT&T C++ manual (Product Reference, Library Manual, and Selected Readings), MacApp 2.0B9 preliminary C++ interfaces (so you can use MacApp from C++),and three 3.5" disks.
Tim Swihart
C++ Product Manager
Thus, all people interested in C++ can now get their copies - and follow this tutorial.
The example that I prepared for you this month is derived from one of the samples on the Apple C++ disks. Apples samples include a rudimentary application framework, some sort of a mini-MacApp, defined in the classes TApplication and TDocument. After last months introduction to some essential features of C++, Ill show you this time how to use this framework to build a small application that opens and closes a window in which some text is displayed and handles one custom menu in addition to the Apple, File, and Edit menus.
Since the base classes, TApplication and TDocument, provide for MultiFinder support, our application will also be fully MultiFinder compatible. I am not reprinting the full TApplication and TDocument framework here, for copyright reasons - the real reason being, of course, that it would make this article about ten pages longer, and those of you who use C++ have those files, anyway. However, well take a short look at the main features of those two classes.
TApplication implements the basic behavior of a Macintosh application. This class provides, among other methods, the constructor for instantiating a new application object, and the public EventLoop routine:
{2}
class TApplication : HandleObject {
public:
TApplication(void);
void EventLoop(void);
etc.
}
Note here that this class is derived from the superclass HandleObject; this is a special class particular to MPW C++, where space for the object is allocated through a handle, not a pointer, to prevent memory fragmentation. Another special superclass is PascalObject, which is used to access class definitions in Object Pascal from C++, necessary for MacApp support. Well discuss these classes in a later column.
Most methods in TApplication are protected so that they can only be accessed by derived classes. They include basic event handlers and initializers which are called before and after the main event loop. Those methods are declared virtual which means they dont have to be defined within the class TApplication itself, and run-time binding will be supported where necessary.
The behavior of our application will be completely determined by the way we re-define TApplications methods. Of the base class, we only need the header file TApplication.h to make its definitions available to our particular implementation; the code for TApplication can be kept in a separate object file or a library.
A simple program would define its own application class, say TMacTutorApp, and override some of the event handlers in TApplication. The main program then just consist of calls to two methods, the constructor and the event loop:
{2}
int main (void)
{
gTheApplication = new TMacTutorApp;
if (gTheApplication == nil) return 0;
gTheApplication->EventLoop();
return 0;
}
A complete Macintosh application in five lines of C++ code! (I dont count the braces). Of course, this simplicity is deceptive; all the work is done in the methods that determine the behavior of the event loop. Our application class, its associated document class, and the methods are implemented in listing 1; the header file that contains the definitions is shown in listing 2.
Our Application
Our application class re-defines TApplications constructor and six private methods. Listing 1 contains the actual code. Lets explain the methods as they are called when the program is executed.
When the application object is constructed, first the constructor of the base class, TApplication, is called. By default, this method initializes all the toolbox managers, determines whether there is enough memory and the system environment is OK to run the program, and does some other initializations. Then, TMacTutorApps constructor is called (listing 1); this method sets up the menu bar and creates one new document (DoNew()).
Any application created using the TApplication framework contains a list of documents, whose maximum number is determined by the constant kMaxOpenDocuments in our applications class definition (Listing 2). The actual handling of this document list is implemented in TApplication itself and need not concern us here. As long as the number of open documents is less than kMaxOpenDocuments, the New, and possibly Open, items in the File menu are enabled; if the maximum number is reached, they will be disabled. This behavior is laid out in the AdjustMenus method. That method is called once on every pass through the event loop (also defined in the base class).
Mouse downs (and other events) are automatically passed on to their respective handlers by TApplication. The routine that we need to override in our class definition to handle menu selections is DoMenuCommand (Listing 1). Here, the basic apple, File and Edit menu selection are treated in a more or less standard way; the fourth menu is our own addition and contains four items to choose from. When one is selected, that item will be checked while the others are unchecked (checking/ unchecking is done by AdjustMenus). Furthermore, the number of the selected item, as well as a corresponding string, are passed on to the open document. The document then knows which message to display in its window.
Our Document
The basic methods that are defined in the TDocument class deal with document display (i.e. window updating, growing/zooming, activate/deactivate), editing (cut/paste, mouse down in content, key down), and file and print handling. All these methods do nothing by default; they need to be overridden in our documents class definition.
Our document is called - what else - a TMacTutorDocument, and the methods we redefine are the constructor, destructor, window draw (private) and update methods. The constructor creates a new window and assigns an initial message to be displayed. When you look at its code (Listing 1), youll notice that the first line looks somewhat funny:
TMacTutorDocument::TMacTutorDocument
(short resID, StringPtr s) : (resID) { etc }
This form of a function call is particular to C++ constructors. When a constructor is called, it will call the constructor of the base class first; this constructor might need another set of parameters. This parameter list is therefore given after the colon. In our case, we pass our windows resource ID to the base class constructor, which then creates a new window according to the resource information. Thereafter our own constructor code is called, which initializes the message string and makes the window visible.
The destructor will only hide our window; the actual deletion of the object (DisposeWindow) is done in the base class, TDocument.
DoUpdate will call our definition of DrawWindow, embedded in calls to BeginUpdate and EndUpdate. DrawWindow itself, which displays the message string in the window, is private; all window re-drawing is handled through calls to DoUpdate.
Methods inside TMacTutorApp set and retrieve the selected menu item number in our document, and set the message string. We therefore need access to these variables, which are private to TMacTutorDocument. Such access is provided through the methods SetDisplayString, GetItemSelected, and SetItemSelected, which are defined inline in the header file (listing 3).
Taking all these definitions together, you have an object-oriented framework for a very simple application. You see how easy it is to expand this framework to your own needs, and how well-separated the different parts of an application are in an object-oriented environment like C++. Application setup, menu handling (proper to the application), and window handling (proper to the document), are clearly distinct, as are the basic behavior (laid down in the application framework) and the user-defined behavior (by overriding the basic methods).
Ill leave it at that for this month; next time well define our own family of objects that can be displayed and manipulated in a document window. If you have questions or comments regarding this column, interesting pieces of C++ code, or suggestions for improvement, feel free to contact me via MacTutor or through the network: LANGOWSKI@FREMBL51.BITNET.
Listing 1: MacTutorApp.cp - our application-specific class implementations
/*--------------------------------------------------------
#MacTutorApp
#
#A rudimentary application skeleton
#based on an example given by Apple MacDTS
#© J. Langowski / MacTutor 1989
#
#This example uses the TApplication and TDocument
#classes defined in the Apple C++ examples
#
#--------------------------------------------------------*/
#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>
// Constants, resource definitions, etc.
#define kMinSize 48 // min heap needed in K
#define rMenuBar 128 /* applications menu bar */
#define rAboutAlert128 /* about alert */
#define rDocWindow 128 /* applications 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
#define item5 5
#include TDocument.h
#include TApplication.h
#include MacTutorApp.h
// create and delete document windows
// call initializer of base class TDocument
// with our window resource ID
TMacTutorDocument::TMacTutorDocument
(short resID, StringPtr s) : (resID)
{
SetDisplayString(s);
ShowWindow(fDocWindow);// Make sure the window is visible
}
TMacTutorDocument::~TMacTutorDocument(void)
{
HideWindow(fDocWindow);
}
void TMacTutorDocument::DoUpdate(void)
{
BeginUpdate(fDocWindow); // this sets up the visRgn
if ( ! EmptyRgn(fDocWindow->visRgn) )
// draw if updating needs to be done
{
DrawWindow();
}
EndUpdate(fDocWindow);
}
// Draw the contents of an application window.
void TMacTutorDocument::DrawWindow(void)
{
SetPort(fDocWindow);
EraseRect(&fDocWindow->portRect);
MoveTo(100,100);
TextSize(18); TextFont(monaco);
DrawString(fDisplayString);
} // DrawWindow
// Methods for our application class
TMacTutorApp::TMacTutorApp(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 for MouseMoved events
fMouseRgn = NewRgn();
// create a single empty document
DoNew();
}
// Tell TApplication class how much heap we need
long TMacTutorApp::HeapNeeded(void)
{
return (kMinSize * 1024);
}
// Calculate a sleep value for WaitNextEvent.
// method proposed in the Apple example
unsigned long TMacTutorApp::SleepVal(void)
{
unsigned long sleep;
const long kSleepTime = 0x7fffffff;
sleep = kSleepTime; // default value for sleep
if ((!fInBackground))
{
sleep = GetCaretTime();
// A reasonable time interval for MenuClocks, etc.
}
return sleep;
}
void TMacTutorApp::AdjustMenus(void)
{
WindowPtrfrontmost;
MenuHandle menu;
Boolean undo,cutCopyClear,paste;
TMacTutorDocument* fMacTutorCurDoc =
(TMacTutorDocument*) 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 )
// is there a window to close?
EnableItem(menu, iClose);
else DisableItem(menu, iClose);
undo = false; cutCopyClear = false; paste = false;
if ( fMacTutorCurDoc == nil )
{
undo = true; // all editing is enabled for DA windows
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);
EnableItem(menu, item5);
CheckItem(menu, item1, false);
CheckItem(menu, item2, false);
CheckItem(menu, item3, false);
CheckItem(menu, item5, false);
CheckItem
(menu, fMacTutorCurDoc->GetItemSelected(), true);
} // AdjustMenus
void TMacTutorApp::DoMenuCommand
(short menuID, short menuItem)
{
short itemHit;
Str255 daName;
short daRefNum;
WindowPtrwindow;
TMacTutorDocument* fMacTutorCurDoc =
(TMacTutorDocument*) 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 (fMacTutorCurDoc != nil)
{
fDocList->RemoveDoc(fMacTutorCurDoc);
delete fMacTutorCurDoc;
}
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 (fMacTutorCurDoc != nil)
{
switch ( menuItem )
{
case item1:
fMacTutorCurDoc->SetDisplayString(\pC++);
break;
case item2:
fMacTutorCurDoc->SetDisplayString(\pSample);
break;
case item3:
fMacTutorCurDoc->SetDisplayString(\pApplication);
break;
case item5:
fMacTutorCurDoc->SetDisplayString(\pHave Fun);
break;
}
fMacTutorCurDoc->SetItemSelected(menuItem);
InvalRect(&window->portRect);
fMacTutorCurDoc->DoUpdate();
}
break;
}
HiliteMenu(0);
} // DoMenuCommand
// Create a new document and window.
void TMacTutorApp::DoNew(void)
{
TMacTutorDocument* tMacTutorDoc;
tMacTutorDoc = new TMacTutorDocument
(rDocWindow,\pNothing selected yet.);
// if we didnt get an allocation error, add it to list
if (tMacTutorDoc != nil)
fDocList->AddDoc(tMacTutorDoc);
} // DoNew
void TMacTutorApp::Terminate(void)
{
ExitLoop(); // exits the main event loop
}
// Our application object, initialized in main().
TMacTutorApp *gTheApplication;
// main is the entrypoint to the program
int main(void)
{
// Create our application object.
// This also initializes the Toolbox --
gTheApplication = new TMacTutorApp;
if (gTheApplication == nil)// if we couldnt allocate object (impossible!?)
return 0;// go back to Finder
// Start main event loop
gTheApplication->EventLoop();
// return some value
return 0;
}
Listing 2: MacTutorApp.h - class definitions
// Class definitions.
// Our document class.
// Only displays some text in a window
//
class TMacTutorDocument : public TDocument {
private:
short fItemSelected;
// string corresponding to menu item selected
StringPtr fDisplayString;
void DrawWindow(void);
public:
TMacTutorDocument(short resID, StringPtr s);
~TMacTutorDocument(void);
// routine to access private variables
void SetDisplayString (StringPtr s)
{fDisplayString = s;}
short GetItemSelected(void) {return fItemSelected;}
void SetItemSelected(short item)
{fItemSelected = item;}
// methods from TDocument we override
void DoUpdate(void);
};
// TMacTutorApp: our application class
class TMacTutorApp : public TApplication {
public:
TMacTutorApp(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);
// routines for our own purposes
void DoNew(void);
void Terminate(void);
};
const short kMaxOpenDocuments = 1;
Listing 3: MacTutorApp.r -
Rez input for our program
#include SysTypes.r
#include Types.r
#define kPrefSize60
#define kMinSize 48
#define kMinHeap (34 * 1024)
#define kMinSpace(20 * 1024)
/* id of our STR# for specific error strings */
#define kMacTutorAppErrStrings 129
/* Indices into STR# resources. */
#define eNoMemory1
#define eNoWindow2
#define rMenuBar 128 /* applications menu bar */
#define rAboutAlert128 /* about alert */
#define rDocWindow 128 /* applications 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
#define item5 5
resource vers (1) {
0x01, 0x00, release, 0x00,
verUS,
1.00,
1.00, Copyright © 1989 J. Langowski / MacTutor
};
resource MBAR (rMenuBar, preload) {
{ mApple, mFile, mEdit, myMenu };
};
resource MENU (mApple, preload) {
mApple, textMenuProc,
0b1111111111111111111111111111101,/* disable dashed line, enable About
and DAs */
enabled, apple,
{
About CPlusMacTutorApp ,
noicon, nokey, nomark, plain;
-, noicon, nokey, nomark, plain
}
};
resource MENU (mFile, preload) {
mFile, textMenuProc,
0b0000000000000000000100000000000,/* program enables others */
enabled, File,
{
New, noicon, N, nomark, plain;
Open, noicon, O, nomark, plain;
-, noicon, nokey, nomark, plain;
Close, noicon, W, nomark, plain;
Save, noicon, S, nomark, plain;
Save As , noicon, nokey, nomark, plain;
Revert, noicon, nokey, nomark, plain;
-, noicon, nokey, nomark, plain;
Page Setup , noicon, nokey, nomark, plain;
Print , noicon, nokey, nomark, plain;
-, noicon, nokey, nomark, plain;
Quit, noicon, Q, nomark, plain
}
};
resource MENU (mEdit, preload) {
mEdit, textMenuProc,
0b0000000000000000000000000000000,/* program does the enabling */
enabled, Edit,
{
Undo, noicon, Z, nomark, plain;
-, noicon, nokey, nomark, plain;
Cut, noicon, X, nomark, plain;
Copy, noicon, C, nomark, plain;
Paste, noicon, V, nomark, plain;
Clear, noicon, nokey, nomark, plain
}
};
resource MENU (myMenu, preload) {
myMenu, textMenuProc,
0b0000000000000000000000000000000,
enabled, Strings,
{
C++, noIcon, nokey, noMark, plain,
Sample, noIcon, nokey, noMark, plain,
Application, noIcon, nokey, noMark, plain,
-, noIcon, noKey, noMark, plain,
Have Fun, noIcon, nokey, noMark, plain
}
};
/* the About screen */
resource ALRT (rAboutAlert, purgeable) {
{40, 20, 190, 360 }, rAboutAlert, {
OK, visible, silent;
OK, visible, silent;
OK, visible, silent;
OK, visible, silent
};
};
resource DITL (rAboutAlert, purgeable) {
{
{120, 240, 140, 320},
Button { enabled, OK },
{8, 8, 24, 320 },
StaticText { disabled,
MacTutorApp: C++ mini-application skeleton },
{32, 8, 48, 320},
StaticText { disabled,
Copyright © 1989 J. Langowski / MacTutor },
{56, 8, 72, 320},
StaticText { disabled,
[Based on examples by Apple MacDTS] },
{80, 8, 112, 320},
StaticText { disabled,
Expand this application to your own taste }
}
};
resource WIND (rDocWindow, preload, purgeable) {
{64, 60, 314, 460},
noGrowDocProc, invisible, goAway, 0x0,
MacTutor C++ demo
};
resource STR# (kMacTutorAppErrStrings, purgeable) {
{
Not enough memory to run MacTutorApp;
Cannot create window;
}
};
resource SIZE (-1) {
dontSaveScreen, acceptSuspendResumeEvents,
enableOptionSwitch, canBackground,
multiFinderAware, backgroundAndForeground,
dontGetFrontClicks, ignoreChildDiedEvents,
is32BitCompatible,
reserved, reserved, reserved, reserved,
reserved, reserved, reserved,
kPrefSize * 1024, kMinSize * 1024
};
type JLMT as STR ;
resource JLMT (0) {
MacTutor C++ Sample Application
};
resource BNDL (128) {
JLMT, 0,
{
ICN#, { 0, 128 },
FREF, { 0, 128 }
}
};
resource FREF (128) {
APPL, 0,
};
resource ICN# (128) {
{ /* MacTutor - JL ICN# */
/* [1] */
$00 01 80 00 00 07 E0 00 00 1F F8 00 00 7F FE 00"
$01 FF FF 80 07 FF FF E0 0F FF 0F F8 07 FF 33 FC
$03 FF FC 38 06 FF FF C8 0C 3F FF FE 08 0F FF D6"
$08 03 FF 96 08 F0 FF 19 09 F8 3E 16 09 88 0C 19"
$08 00 00 16 08 00 00 10 0B 1E 78 D0 0B FF FF D0"
$09 FF FF 90 FC 7E 7E 3E 96 00 00 6A D3 FF FF CA
$52 00 00 4A 53 FF FF CB A6 38 70 69 DC 44 88 3F
$1F 38 73 98 38 87 04 4C 67 08 83 86 7F FF FF FE,
/* [2] */
$00 07 E0 00 00 1F F8 00 00 7F FE 00 01 FF FF 80"
$07 FF FF E0 1F FF FF F8 1F FF FF FC 0F FF FF FE
$07 FF FF FC 07 FF FF F8 0F FF FF FE 0F FF FF FE
$0F FF FF FE 0F FF FF FF 0F FF FF FE 0F FF FF FF
$0F FF FF F6 0F FF FF F0 0F FF FF F0 0F FF FF F0"
$0F FF FF F0 FF FF FF FE F7 FF FF EE F3 FF FF CE
$73 FF FF CE 73 FF FF CF E7 FF FF EF DF FF FF FF
$1F FF FF F8 7F FF FF FE FF FF FF FF FF FF FF FF
}
};
Listing 4: MacTutorApp.make - the make file
# File: MacTutorApp.make
# Target: MacTutorApp
# Sources: MacTutorApp.cp
# MacTutorApp.h
# MacTutorApp.r
# TApplication.cp
# TApplication.h
# TDocument.cp
# TDocument.h
# TApplication.r
# Created: Wednesday, October 18, 1989 8:15:31
OBJECTS =
MacTutorApp.cp.o TApplication.cp.o TDocument.cp.o
MacTutorApp.cp.o
MacTutorApp.make MacTutorApp.cp MacTutorApp.h
CPlus MacTutorApp.cp
TApplication.cp.o
MacTutorApp.make TApplication.cp TApplication.h
CPlus TApplication.cp
TDocument.cp.o
MacTutorApp.make TDocument.cp TDocument.h
CPlus TDocument.cp
MacTutorApp MacTutorApp.make {OBJECTS}
Link -w -t APPL -c JLMT
{CLibraries}CRuntime.o
{OBJECTS}
{Libraries}Interface.o
{CLibraries}StdCLib.o
{CLibraries}CSANELib.o
{CLibraries}Math.o
{CLibraries}CInterface.o
{CLibraries}CPlusLib.o
#{CLibraries}Complex.o
-o MacTutorApp
MacTutorApp MacTutorApp.make MacTutorApp.r
Rez MacTutorApp.r -append -o MacTutorApp
MacTutorApp MacTutorApp.make TApplication.r
Rez TApplication.r -append -o MacTutorApp