Volume Number:		6
Issue Number:		9
Column Tag:		MacOOPs!

Related Info: Window Manager QuickDraw TextEdit

Object Shell, Part II

By Dr. Christian Stratowa, Vienna, Austria

Part 2: Application-specific Units

Let me start the second part of my article once again with a statement, this time with the first sentence of the TMLetter: “Apple is giving notice to Macintosh developers that object-oriented programming (OOP) will become the only way to write Mac software.” I really hope this statement does not mean that in the future Apple will force programmers to use MacApp. Although I don’t have MacApp yet, from what I have seen in the different articles published in MacTutor, I have the feeling that I won’t like it. Once upon a time...Apple has started the computer revolution by giving people the freedom of personal computing. Now that Apple seems more and more to adopt IBM-like behaviour let me say: “Freedom to the programmers to adopt their own programming style and to use the language of their choice!” Programming is still an esthetic art and having a uniform user interface (which is surely of great benefit to the users) does not necessarily mean to have to adopt a uniform programming style.

Last time I have presented the general part of our shell program, which needs not be changed when you want to use ObjectShell for your own purposes. So let’s now talk about the units specific to our demo application.

Adding your own menus

Unit MyMenus allows us to attach all menus specific to our application. Here we make use of Apple’s new “Hierarchical Menus” feature, where any menu item can be defined as submenu. So we define an object TSubMenu, whose method Create inserts a submenu (see IM V-236). In our program we make use of this feature not only in menu “Text” where Font, Size, Style and Justification are arranged as submenus, and in “Color” with submenus TForeCMenu and TBackCMenu, but we do also define item “New” of our standard “File” menu as submenu to be able to create “NewText” or “NewPict” documents. We can do this by creating submenu TNewMenu without having to change any code in our unit StdMenus. Every submenu item can itself be another submenu, although Apple states that only one level of hierarchical menus should be used. In our demo program we create another submenu level by defining TNewPictMenu and TNewTextMenu to let the user choose the window type. Normally you would delete this level.

We can open windows containing either TEXT or PICT documents which use different menus. For this we want to change the appearance of the menubar depending on the type of window becoming Frontwindow. Therefore procedure SetMyMenuBar, which is called from DoActivate every time a window will be activated, does change the whole MenuBar by calling SwitchMenus. When no window is in front, all but the three standard menus will be deleted from the menubar. In the case Frontwindow is a desk acessory I decided for demonstration purposes to disable the application-specific menus only although we could have also deleted them in this case. (I have put the necessary call to SwitchMenus in parenthesis.) Procedure SwitchMenus does insert or delete the necessary menus by calling DoInsertMenu. This procedure requires parameter vMenuHdl besides vRsrcID, because it is not possible to call GetMenuHandle(vRsrcID), when a menu is not installed in the menulist.

When a userwindow becomes activated, we want the current menu settings to be marked, e.g. for text the current Font, Size, Style and Align menu items should be indicated with a checkmark. This is pretty straight foreward. For text procedure SwitchMenus calls CheckFontMenu, CheckSizeMenu etc. Procedure CheckFontMenu does for example get the current font from the GrafPort (thePort^.txFont) and does call SetCheckMark if vFontName equals vCurrentFont. It has also to call OutlineFontSize for every RealFont in the System. Procedure CheckStyleMenu is a little more tricky, because Apple has decided to define Style as set of type StyleItem [see IM I-152]. Together with style “Plain” there exist eight style items, therefore I have decided to use the bits of one byte for the style setting. For this purpose I defined a field variable fMyHdl of type Handle in TDocument. All procedure CheckStyleMenu has to do is to set the corresponding bits. (Because a Handle is defined as ^^SignedByte the initial setting “Plain” is: fMyHdl^^:= -128.) Similarly, when we select or unselect a style item, TStyleMenu.Choose sets or clears the corresponding bit.

For graphics we have only to call SetCheckMark every time a graphics window becomes activated or the user selects an item from the “Graphics” menu or one of the “Color” submenus. (To save some space in this article, I have decided not to colorize the “Color” submenu items. With new ResEdit 1.3 (one.three!) it is much too easy to do, anyway.)

Documents - What the Mac is Made for

So far we have learned how to deal with Mac specific stuff, but every computer is built for one purpose only - to process our documents.

As mentioned earlier, our program can handle text and graphics. In unit MyDocuments we define subclasses TTextDocument and TPictDocument. The document type itself is then set in TWindow.DoNew in the already known manner. However, creating a new document this way does have its disadvantages, too: We have to place every field, which has to be set from outside the object, in ancestor class TDocument. Let us take textedit record’s handle fTextHdl as an example. This is clearly a field variable, which does only belong to subclass TTextDocument. But if we define it there the compiler will generate an error message in method Choose of our submenus, where we have set e.g. fTextHdl^^.txFont. Isn’t this a limitation of the ObjectPascal compiler? (You will probably say objects should be encapsulated and fields not changed from outside directly.)

Since we are already talking about text let’s have a closer look.

Typewriter’s Mac

Before creating a new fTextHdl for our textedit record in DoNew we have to define its view rectangle fViewRect and destination rectangle fDocRect. These two rectangles have also to be set in our Update routine, otherwise you will be in trouble when for example selecting text with TEClick. You may be wondering why we declare field fViewRect in addition to fViewRgn. This is necessary to be able to inset fViewRect by kTextMargin. Insetting fViewRgn would lead to strange looking results in the case you want to place some controls within your window and use a background color other than white.

Typing itself is handled in method KeyPress. In this routine we inform the user when the number of characters in the text exceeds MaxInt during typing by displaying a dialog box.

Every time we SetColor or change Font, Size, Style or Justification of our text method ReDraw does the necessary calculations before calling TECalText and invalidating fViewRgn to force an update event.

The World of QuickDraw

Our graphics example shows how to deal with the following features:

• selecting the desired shape from menu “Graphics”

• clicking anywhere within fViewRgn to determine where the shape should be drawn

• popping up a dialog box for setting the shape parameters every time you click the mouse button within the view region

• changing fore and background color any time you want

This time we create every shape in DoNew as a distinct object oOvals, oSpirals, together with its connected oDialog box. Only after having clicked the mouse button in fViewRgn we are setting the choosen shape equal to oShape to be able to use field oShape in the other methods.

Method ClickInDoc does first call DoDialog to allow the user to set the shape parameters and then calls self.ReDraw. But keep in mind that the user could have scrolled fDocRect before clicking in the view region to position the draw origin, so you have to adjust field oShape.fPt accordingly first. When the dialog window has been closed all needed update and activate events are generated automatically. In our case automatically updating is not necessary, because the whole view region will be redrawn anyhow since we clip to fViewRgn and call Update ourselves, so we call ValidRgn(fViewRgn) first to prevent redrawing the part of fViewRgn covered by the dialog box twice.

The actual drawing is done in method ReDraw using QuickDraw’s picture record. QuickDraw lets you save a sequence of drawing commands between calls OpenPicture and ClosePicture and “play them back” later with a single procedure call [IM I-158]. To be compatible with MacDraw we have to embed picture comments picDwgBeg and picDwgEnd. PicComments, which do not have an effect on the displayed image, are used to apply additional information when pictures are transmitted from one application to another. Here we use also PicGrpBeg and PicGrpEnd to group our QuickDraw calls together to act like one object. Our application supports scrolling, therefore we have first to limit drawing to region vClipRect within the portRect of QuickDraw. Otherwise offsetting the picture rectangle just one pixel to the right or bottom will set the clipping rectangle to the empty rectangle and the whole picture gets clipped (see IM I-190 and MT 4/86 p.57).

There are three ways to redraw pictures, when we scroll or resize the drawing window:

1, We could store the picture as an offscreen bitmap. This would allow fast scrolling but uses lots of RAM, especially when drawing in color with new 32bit ColorQuickDraw.

2, We could recalculate our drawing for every update event like MacDraw does. This approach is unacceptable in the case our drawing contains e.g. a graph obtained from a set of differential equations, or a Mandelbrot fractal, where calculation times easily exceed one hour. In that case recalculating the picture should not be done for saving and printing our documents either.

3, We could calculate our drawing only once and define it as QuickDraw picture, then redraw it when necessary with procedure DrawPicture. This approach should also be used for saving and printing.

In my example I use the third possibility which seems to me to be the best one. However, to be able to change the color of our drawing every time we select a different color from the Color menu, we have to define our picture in method ReDraw instead of method ClickInDoc, an approach not possible for long calculation times. (For more information about pictures and picComments see MT 4/86 p.56, MT 10/87 p.66 and MT 6/88 p.40.)

Mac’s Way to Communicate

As mentioned earlier, before drawing our picture we put up a dialog box to get all of the shape parameters we need. Object TDialog contains variable fDlogItems, which determines the size of string array fStr, the array of editable text fields fStr itself, and a boolean flag fDFlag as field variables. Array fStr stores the parameters we input so that the next time we select the dialog box our new parameter settings will be displayed. The flag field is set to TRUE when we press OK after setting the dialog parameters or to FALSE when we cancel the dialog, in which case the default values are displayed the next time the dialog box is called. Fig.5 shows the dialog box, which will be displayed after calling oOvals.DoDialog. As you can see it does not only contain editable text fields but also a popup menu, which I have implemented so that you can see how Apple’s demo example (Macintosh developer technical sample code disk) works in a real application. It is pretty straight foreward, you only have to take care to preserve the old grafport in filterfunction MyFilter before setting the grafport to vDPtr.

Method DoDialog does first call CenterMyDialog to make sure the dialog box will be centered for every screen size used. This is always possible because records DialogTemplate and AlertTemplate contain field boundsRect, which stores the global coordinates of the Dialog or Alert window [see IM I-423]. After determining dialog’s width and height procedure CenterDialogBox calculates the new TopLeft position of boundsRect. Before allowing the changed resource being purged from the heap CenterMyDialog has to call SetResPurge, so that the resource data can be written out to the resource file.

The parameters stored in array fStr when the user presses the OK button, are converted to numbers in method TShape.Create. I did not implement error checking in case the user types a non-numeric entry in the dialog.

Cut, Copy and Paste

Our application does implement the Edit menu. This is pretty straight forward for text, where we can use the editing routines from TextEdit. The only difference to other people’s code is that after calling TECut or TECopy we transfer the content of TextEdit’s private scrap immediately to the desk scrap. By doing this we need not take care to transfer the private scrap when another window gets activated or when running under MultiFinder. (Apple’s new TextEdit routines TECut and TECopy write both text and its associated style information directly to the desk scrap, anyhow. [IM V-267]) Before pasting we check first if the desk scrap contains text and if the length of the current text plus the text to be pasted does not exceed MaxInt in which case we put up an alert box informing the user. In method ApplTask we enable menu items Cut and Copy only when text is selected, and Paste only when the scrap is not empty.

Setting up editing for pictures is a little more complicated. We have to know exactly when to dispose of vScrapHdl we have created before, and when to call KillPicture. For menu items Cut and Copy we have to set vScrapHdl to nil before disposing it, for menu item Paste we are not allowed to dispose of vScrapHdl because it has been converted before to type PicHandle. At the end of method Edit we have to call self.Update if the content of our document has changed. In our demo application we have implemented the Edit menu mainly to be able to paste pictures into other applications like MacDraw. Pasting a picture within our program, although possible, does not give you any advantage, in contrast you are not able to change the color afterwards.

Saving and Opening Files

Once we have typed text or played around with different shapes we want to store our work to disk. This is done with TWindow function Saved. When we have choosen “Save as...” from the File menu (vSaveAs) or want to save a document the first time (vNewFile), we call the standard file dialog. If vReply is good we do first check for DuplicateFileName and then create a new file. DuplicateFileName makes recursive calls to nextWindow to check if a window with title vFileName is already open. If this is the case we rename the old window “Untitled”, delete its file and set flag fChanged of the old document to TRUE. This forces the program to ask the user if s/he wants to save the old document before closing it. In any case we open the file, call oDocument.DoSave, and close the file.

For text we set the file position to the start of the file and use TextEdit record handle hText to write text into the file. (Remember to lock the handle before dereferencing it.)

In the case of our drawings we have first to write a 512 byte blank header to disk before we can write our QuickDraw picture document into the file. This will enable MacDraw to open our PICT file and use its default settings.

Opening documents is done similarly. We call the standard file dialog and if vReply is good and the file is not already open, we create a new window by calling DoNew. We open then the file in window’s method DoOpen, call oDocument.DoOpen, set the new window title, force an update event, and close the file.

When opening a text file we check first if vFileSize is not larger than allowed by TextEdit before reading in the text. We set the caret to the end of our document and scroll the text to the bottom.

Because we have saved our picture as a MacDraw document we have to set the file position to 512 bytes from start before reading in the picture. In this way we are also able to open MacDraw documents saved as PICT documents. To be able to do this we have to set fDocRect equal to the picture frame otherwise the MacDraw document would be displayed with distortion.

Using the File Manager to save and open files involves a lot of error checking, so we embed most of its routines in our boolean function OSError, which displays an error message when an error has occured. It would be good programming style and helpful to the user if the dialog box would not only show the error ID number but a description of the error, too. In order to save space in this article we describe only the errors “Duplicate File name” and “File already open”, in all other cases we display vErrNr only.

When closing a file whose document field fChanged has been set to TRUE, an alert box pops up asking the user to save the document before closing it. When the user presses “Cancel” the flag gQuitting will be set to FALSE. This is important in case “Quit” was choosen from the File menu, because procedure DoQuit will then discontinue closing further windows and not set flag gDone.

When the last application window will be closed or vNextWindow is a desk accessory gCloseFlag will enable us to SetMyMenuBar.

Making Hardcopies

Although some people have promised us a paperless world with the advent of computers quite the opposite became true. To enable our user to waste paper too we support printing text and graphics.

Printing a document using the Printing Manager involves a lot of opening and closing stuff. At first we have to open the printer resource file and the Printer Driver (PrOpen) in procedure DoPrint called from the standard File menu. Then we validate our print record, put up the standard printing dialog box and pass control to oWindow.DoPrint before calling PrClose. In unit StdWindows we open the printing grafport after having saved our current grafport. We DisplayPrintDialog to enable the user to cancel the printing process. In case of draft printing the actual printing is done in TDocument.DoPrint, where each page is opened, printed and closed separately. In the other cases each page is prepared for printing only once by drawing into the printing port and writing it to disk as part of a spool file. The actual printing is then done in TWindow.DoPrint by calling PrPicFile. This procedure images and prints a spool file containing a previously spooled document.

While this time printing graphics is easy by simply calling DrawPicture, you only have to reset vDocRect in case the user has scrolled the picture before choosing ‘Print’, printing text involves more work. First we calculate the bounding rectangle our edit record will use for wrapping text by insetting vPageRect. Then we create a new TextEdit record which will draw into the printing port, determine vPageHeight, and copy the text handle and text length from the active window’s main edit record fTextHdl into our new one, vTextHdl. After wrapping the text to vPageRect we open each page separately and draw our text by calling TEUpdate. Before closing the page we have to offset our text so that the next part of our document can be drawn on the following page. When done we dispose of the edit record, but first we have to clear its text handle hText to nil. Otherwise we would automatically deallocate the text while our window still needs it (MR 3-168).

Multifinder Support

Trying to support Multifinder was pretty hard because the only information I have until now comes from two articles in MacTutor (MT 11/87 and 2/88), which I didn’t quite understand, so I had to play around to get the code right. And this is how I think Multifinder is working: When you switch between different applications under Multifinder, the application which comes to the front gets activated. Multifinder will not only feed an activate event to the proper window, but will also post a resume/suspend event in the event queue (App4Evt). When you have set in resource ‘SIZE’, that your application supports resume/suspend events then you should not use these activation events (is this true?) but handle the necessary activations yourself. Since App4Evt is an application defined event type, then depending on the state of gEvent.message, which, for activate events, is a pointer to the window effected, you have to set the activate/deactivate flag yourself. Therefore, in procedure DoMFEvent we are forcing an activate/deactivate event by setting the activeFlag bit of the EventRecord field gEvent.modifiers. This field is an integer, therefore we have to set/clear bit 15 (because the bit-numbering convention of the toolbox is the reverse of the one generally used on the 68000 processor). Then when FrontWindow is ours we call oWindow.Activate as usual. This code does now really work. To see, that it is also necessary, delete all code in procedure DoMFEvent and recompile the program. When you open now the program under Multifinder then at first sight you won’t see any difference. But when you look carefully you will see, that after switching between programs our grow box and scroll bars will not be activated properly.

Although set up for mouse moved events, we are not supporting this feature of MultiFinder and have therefore set gMouseRgn to nil. I have only one monitor so I could not test if the necessary region arithmetics would be ok on multiple monitors.

A Personal Outlook

Now that I have finished to outline a typical shell program for the Mac, which I hope some of you may find useful, let me take the opportunity to make some personal remarks about the future of computers, Apple computers, and programming.

It seems clear to me that object-oriented programming will be the software-approach of the future. However, I don’t think that MacApp will have a bright future, because first it does restrict programmer’s thinking too much, and second it is limited to the Mac only. (Besides that I don’t see any advantage in learning more than 500 MacApp procedures over learning more than 500 ROM calls.) The way of the future seems to lie more in GAOOP - graphic assisted object-oriented programming, a way outlined in Steve Jobs’s NextStep, and to a more limited content also in HyperCard. Maybe Smalltalk will finally get the attention it deserves, although for some strange reason Apple has never promoted it officially. Using Smalltalk scientists at Canon’s European research center have recently developed a visual programming language, called VPL, which enables nonspecialists to manipulate images on a computer screen. I have the feeling that Apple is more and more loosing ground.

Talking about Apple - what is the difference between IBM and Apple? Most people would probably agree that IBM became world’s largest computer company not because of innovative products but (at least partly) because of its known customer service, a word that does not even exist at Apple. At mainframe times customer service and compatability to existing operating systems was more important than staying at the edge of technology. In contrast to IBM, Apple became a billion dollar company due to only two innovative products, the Apple II and the Macintosh. For personal computers of today innovation and userfriendliness is more important than compatibility to existing systems (even if this system is UNIX). This will be even more important tomorrow.

What is the hardware approach of the future, and where will Apple be? Sun and HP have already come out with RISC machines, even Atari has recently presented an innovative computer, the Atari Transputer Workstation. Meanwhile Apple has presented a third Mac II clone (IIci) without graphics processor. (How can a company claiming to make one of the best graphics computers, still design its hardware without at least one graphics processor?) Maybe Apple is already too large to be innovative. I think Apple will only survive if it will be the first to present the power of an old Cray 1 on the desktop at the cost of a Mac II. Where are the NeXT Jobs at Apple? (Note added in proof (Oct89): On a trip to New York I had the possibility to get a demonstration of the NeXT cube. I am really sorry for Apple but after having seen and heard(!) the NeXT in action I have almost lost all interest in working with or programming the Mac. If I would have the money I would buy one immediately. Forget the Mac, join the NeXT! - or at least get a demonstration yourself.)

Be it RISC or transputer or another processor technology, the real hardware innovation of the near future will be parallel processing, which will stay with us forever (!), because this is how our brain works. Neural network design will also become more and more important. In the farther future optical computing will give parallel processing a completely new meaning. And then will come the quantum computer, which may at last be able to think. I guess I’ll better stop here!

Continued in next frame

Volume Number:		6
Issue Number:		9
Column Tag:		MacOOPs!