TweetFollow Us on Twitter

Winter 92 - SIMPLE TEXT WINDOWS VIA THE TERMINAL MANAGER

SIMPLE TEXT WINDOWS VIA THE TERMINAL MANAGER

CRAIG HOTCHKISS

[IMAGE Hotchkiss_rev1.GIF]

A major feature of System 7 is the fact that the Macintosh Communications Toolbox is built in and available for all to use. This article presents code that uses the Communications Toolbox Terminal Manager to implement a simple text window that can be dropped into any application. The window is useful for displaying debugging or status information such as variable values or memory usage during application development.


Many times, when writing code, I've wished I had some sort of text repository, a place to write some quick text. I tried to use TextEdit for this at first, but its structures grow as you add text, so my memory accounting became confused. Sprinkling DebugStr calls throughout the code told me what I needed to know most of the time, but they were interruptive to both the user interface and timing- sensitive functions. Finally, I turned to the Terminal Manager because in addition to a terminal tool it contains the nuts and bolts necessary to display a text window and uses a fixed amount of memory.

TermWindow, included on theDeveloper CD Series disc, consists of a few simple routines that use the Terminal Manager and a terminal tool to display text in a Macintosh window. The package can be used in any application for purposes such as displaying variable values, heap checks, memory usage, and routine paths. I've even used some features of the terminal tool to grab attention, like having text blink when I encounter an OSErr or when memory begins to get tight.

Figure 1 shows a sample TermWindow terminal emulation window. I used the Developer Technical Support (DTS) Sample application (included with MPW) and the Apple VT102 tool to produce the display. The double-high/double-wide text shown in the figure is a feature of the VT102 emulator. I displayed it by writing the escape sequences shown on the next page to the window. (Two lines are needed for double-high text, one to display the top half of the line, and one for the bottom half.)

<ESC>#3HELP! I'm trapped in here!
<ESC>#4HELP! I'm trapped in here!

[IMAGE Hotchkiss_rev2.GIF]

Figure 1A TermWindow Window

THE HEADER FILE

The file TermWindow.h defines a basic TermWindowRec structure that TermWindow uses internally for housekeeping and for storage of other structures, including the handles for the terminal and control records.
struct TermWindowRec
{
    WindowRecord    fWindowRec;     // so it can be a WindowPtr
    short           fWindowType;    // for application use
    TermHandle      fTermHandle;    // CTB terminal handle
    TermEnvironRec  fTermEnvirons;  // environment info
    ControlHandle   fVertScroll;    // vertical scroller
    ControlHandle   fHorizScroll;   // horizontal scroller
    Point           fMinWindowSize; // min. width/height of window
};
typedef struct TermWindowRec TermWindowRec;
typedef TermWindowRec *TermWindowPtr;

Six prototype routines, used to put TermWindow to work in an application, are also defined in the header file TermWindow.h.

pascal  OSErr   InitTermMgr(void);
pascal  OSErr   NewTermWindow(TermWindowPtr *termPtr,
                                const Rect *boundsRect, 
                                ConstStr255Param title, 
                                Boolean visible,
                                short theProc, 
                                WindowPtr behind,
                                Boolean goAwayFlag,
                                Str31 toolName);
pascal  OSErr   DisposeTermWindow(TermWindowPtr termPtr);
pascal  Boolean IsTermWindowEvent(TermWindowPtr termPtr, 
                                const EventRecord *theEventPtr);
pascal  void    HandleTermWindowEvent(TermWindowPtr termPtr, 
                                const EventRecord *theEventPtr);
pascal  OSErr   WriteToTermWindow(TermWindowPtr termPtr,
                                Ptr theData, Size *lengthOfData);

HOW TO USE TERMWINDOW

The six TermWindow routines are easy to use. After normal Macintosh manager initialization, you'll initialize the Terminal Manager with a call to InitTermMgr and then call NewTermWindow. The NewTermWindow function allocates the TermWindowPtr, terminal handle, and control handles. It also creates a Macintosh window complete with scroll bars and then attaches the terminal emulation region to the window with a call to TMNew. (See the next section for more on initialization.)

There are two functions to handle events, IsTermWindowEvent and HandleTermWindowEvent. These should be placed in your application event loop. IsTermWindowEvent determines whether the incoming event is for the emulation window by looking at the EventRecord structure, and it also provides time to the terminal emulator by calling TMIdle. HandleTermWindowEvent is a dispatcher that routes the event to routines that in turn call the Terminal Manager to process the event. These routines are discussed in more detail in the section "Handling Events."

The WriteToTermWindow routine, discussed later in this article under "Writing Text," uses the Terminal Manager to display your data in the terminal emulation window. And finally, DisposeTermWindow performs window and structure cleanup.

INITIALIZATION

The InitTermMgr routine prepares to initialize the Terminal Manager by checking the status of three Gestalt selectors: gestaltCTBVersion, gestaltCRMAttr, and gestaltTermMgrAttr. (We don't have to check for Gestalt, since MPW 3.2 contains the code to make Gestalt work.) The gestaltCTBVersion selector tells us which version of the Communications Toolbox is available, thereby letting us know that it exists. The gestaltCRMAttr and gestaltTermMgrAttr selectors tell us, respectively, whether the Communications Resource Manager (which must be initialized for tool resource handling) and Terminal Manager are available for use. InitTermMgr then calls the Communications Toolbox initialization routines if each Gestalt call returns a value of true. It all looks like this:
pascal OSErr InitTermMgr(void)
{
    OSErr   result = noErr;
    Boolean hasCTB, hasCRM, hasTM;
    long    gestaltResult;
    
    hasCTB = (Gestalt(gestaltCTBVersion, &gestaltResult) ? 
                            false : gestaltResult > 0);
    hasCRM = (Gestalt(gestaltCRMAttr, &gestaltResult) ? 
                            false : gestaltResult != 0);
    hasTM = (Gestalt(gestaltTermMgrAttr, &gestaltResult) ? 
                            false : gestaltResult != 0);
    if ((hasCTB) && (hasCRM) && (hasTM))
        if (noErr == (result = InitCRM()))
            if (noErr == (result = InitCTBUtilities()))
                if (noErr == (result = InitTM()))
    
    return (result);
} /*InitTermMgr*/

You may wonder whether the Communications Toolbox requires that the Macintosh Toolbox managers be started up at initialization time. The Communications Toolbox managers are loaded in the system heap, so you may have other reasons for starting them up in your initialization routine, but TermWindow's only requirement is that InitTermMgr be called at some point beforeNewTermWindow. Because the NewTermWindow routine has the potential to allocate nonrelocatable memory, calling InitTermMgr and NewTermWindow at initialization removes the possibility of heap fragmentation.

NewTermWindow begins by validating each parameter that was passed and assigns default values if necessary (see Table 1 below; refer to "The Header File" earlier in this article for the NewTermWindow declaration). You might notice that a good deal of the parameter list to NewTermWindow is very similar to that for the NewWindow function in the Macintosh Toolbox. The NewTermWindow parameter list is designed to provide as much window control as possible when calling NewWindow, while also adding the functionality for the terminal emulation region. Calls to NewControl attach scroll bars to the window being created.

Table 1 NewTermWindow Defaults

Parameter NameDefault Value
termPtrPointer allocated for TermWindow storage
boundsRectFrontWindow window size
title"\pStatus"
visibleTrue
theProcZoomDocProc
behindFrontWindow
goAwayFlagFalse
toolNameTMChoose user setup dialog box

Once the Macintosh window is ready, NewTermWindow attaches the terminal emulation region to the window with a call to TMNew. Parameters to the TMNew routine tell the terminal tool, via the Terminal Manager, how to set up the emulation. (Terminal tools, not the Terminal Manager, implement the emulation.) The basic TMNew prototype is as follows:

pascal TermHandle TMNew(const Rect *termRect,
            const Rect *viewRect,
            TMFlags flags, short procID, WindowPtr owner,
            TerminalSendProcPtr sendProc, 
            TerminalCacheProcPtr cacheProc,
            TerminalBreakProcPtr breakProc, 
            TerminalClikLoopProcPtr clikLoop, 
            TerminalEnvironsProcPtr environsProc, 
            long refCon, long userData);

In TermWindow's case, NewTermWindow sets termRect and viewRect to the portRect of the window's grafPort minus the scroll bar area and sets the flags parameter to 0L. (This enables the terminal tool to put up custom menus or provide error alerts to the user.) The procID parameter is a terminal tool reference number (obtained with TMGetProcID) that tells the Terminal Manager which tool to use. The owner parameter is set to the WindowPtr of our Macintosh window. The procedure pointers, refCon, and userData are all set to nil or 0L.

termPtr->fTermHandle = TMNew(&termRect, &termRect, 0L, procID,
                            (WindowPtr)(*termPtr), nil, nil, nil, 
                            nil, nil, 0L, 0L);

HANDLING EVENTS

Your application's main event loop should use the two event-handling routines, IsTermWindowEvent and HandleTermWindowEvent, to process events for the emulation window and to determine whether the event has already been handled. I use the following fragment just after calling WaitNextEvent; it sets the gotEvent flag to false when TermWindow has processed the event, so that I don't try to handle the event twice.
if (IsTermWindowEvent(&gTheEvent, gTermWindowPtr)) {
    HandleTermWindowEvent(&gTheEvent, gTermWindowPtr);
    gotEvent = false;
}
IsTermWindowEvent uses FindWindow or the message field of the event record to determine whether the event is for the terminal window. (SeeInside Macintosh Volume I, page 250, for details.) IsTermWindowEvent is also a convenient place to give the terminal tool idle time; it calls TMIdle to give the tool a chance to draw text or blink the cursor. (Some terminal tools also have the ability to display blinking text; that would be done here also.)

The HandleTermWindowEvent routine is fairly straightforward, especially if you've written window- and scroll-handling code before. As is true when handling normal windows, the what field of the event record defines the work to be done. Terminal Manager routines exist for most of this work, so handling events is primarily a matter of calling the right routine at the appropriate time. For example, window activation and deactivation are communicated to the tool with a call to TMActivate.

TMActivate(termPtr->fTermHandle, 
            (0 != (theEventPtr->modifiers & activeFlag)));

Figure 2 illustrates how a message like TMActivate is routed to accomplish its goal. The Terminal Manager receives the TMActivate call and routes the tmActivateMsg message to the terminal tool. The terminal tool then takes the opportunity to call Macintosh Toolbox routines such as InsertMenu or RemoveMenu (if the tool uses a custom menu, as the VT102 tool does) to keep the screen up to date.

Update events are handled by a call to TMUpdate sandwiched between BeginUpdate and EndUpdate. You'll just need to pass TMUpdate the update region freshly calculated by BeginUpdate. Of course, if you check for an empty region first, you won't have to call TMUpdate at all.

BeginUpdate((WindowPtr)termPtr);
    if (nil != ((WindowPtr)termPtr)->visRgn)
        TMUpdate(termPtr->fTermHandle, ((WindowPtr)termPtr)->visRgn);
EndUpdate((WindowPtr)termPtr);

[IMAGE Hotchkiss_rev3.GIF]

Figure 2 Calling TMActivate

Mouse-click handling is also fairly traditional. FindWindow is used to determine where in the window the click took place, and Terminal Manager routines are called to let the terminal tool know what to do. When a zoom or grow event causes the size of the emulation rectangle to change, the window's portRect gets passed to TMResize. If FindWindow returns inContent, FindControl is used to determine the control in which the click occurred, so that TermWindow will know whether to scroll horizontally or vertically. The partCode returned from FindControl tells how much to scroll by indicating the part of the control where the click took place. If FindControl returns nil for the ControlHandle parameter, the click is in the emulation region and TMClick is called.

WRITING TEXT

Writing data is easy via the WriteToTermWindow routine. Here's an example of a WriteToTermWindow call with tempString declared as a char array:
sprintf(tempString, "Hello, world");
dataLength = strlen(tempString);
osResult = WriteToTermWindow(termPtr, tempString, &dataLength);

In a debugging situation, you might want to do something like the following to keep track of heap size:

gAppHeapRef -= FreeMem();
if (gAppHeapRef) {
    sprintf(tempString, "\t\t#M# App. heap grew by %ld bytes",
                    gAppHeapRef);
    dataLength = strlen(tempString);
    osResult = WriteToTermWindow(termPtr, tempString, &dataLength);
}

WriteToTermWindow hands the data off to the terminal tool, via a call to TMStream. You might be tempted here to think that the data should appear in the window immediately, but it doesn't--it's simply put in the terminal tool buffer. The terminal tool waits for a TMUpdate or TMIdle before actually writing to the window. Another point to remember when working with terminal tools is that display fonts are controlled by the terminal tool; in fact, many use specific terminal fonts.

NOW IT'S YOUR TURN . . .

That's really all there is to using this simple text window. Now that you have some base code to work from, you might want to add the communication abilities needed to talk to another computer by using Connection Manager calls like CMRead or CMWrite and telling the terminal tool when to use them with procedure pointer parameters to TMNew. How about extending TermWindow to write all data displayed to a file? Or if you're really up to a challenge, try adding a scroll-back cache to store data that gets scrolled out of the emulator. Just scrolling the data around is not too difficult, but brush up on your region handling when you try to work with selections.

I hope you find the TermWindow package useful. Put it to work, add some features, and pass it on. Everything should evolve over time.

CRAIG HOTCHKISS works on the Connectivity team in Apple's system software group. When he's not pondering new ways for you to discover the world via your Macintosh, you might catch him practicing maneuvers with his stunt kite, playing chess, or "on his way" to a volleyball game. Before coming to Apple, Craig spent several years (in the great state of theworld champion Twins) at the telephone company frustrated with DOS in preparation for database work on PDP and VAX machines.*For more details on using the Macintosh Communications Toolbox, see Inside the Macintosh Communications Toolbox,   by Apple Computer, Inc. (Addison-Wesley, 1991).*

THANKS TO OUR TECHNICAL REVIEWERSJames Beninghaus, Mary Chan, Byron Han *

 
AAPL
$100.99
Apple Inc.
+0.88
MSFT
$46.27
Microsoft Corpora
-0.17
GOOG
$574.86
Google Inc.
-1.50

MacTech Search:
Community Search:

Software Updates via MacUpdate

QuickBooks 2015 16.0.0.1352 R1 - Financi...
QuickBooks 2015 helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save.... Read more
Mac DVDRipper Pro 5.0.1 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
Apple OS X bash Update 1.0 - Fix for sec...
The OS X bash Update fixes a security flaw in the bash UNIX shell on OS X 10.9.5 (also on OS X 10.8 and 10.7 [see Related Links below]). OS X 10.9.5 or later Downloads for OS X 10.8 and OS X 10.7 in... Read more
SyncTwoFolders 2.0.5 - Syncs two user-sp...
SyncTwoFolders simply synchronizes two folders. It supports synchronization across mounted network drives and it is a possibility to run a simulation showing in a log what will be done. Please visit... Read more
FinderPop 2.5.7 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more
VueScan 9.4.45 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
LibreOffice 4.3.2.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
calibre 2.4 - Complete e-library managem...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more
Default Folder X 4.6.9b1 - Enhances Open...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more
Beamer 2.0.4 - Stream any movie file fro...
Beamer streams to your Apple TV.... Plays any movie file - Just like the popular desktop movie players, Beamer accepts all common formats, codecs and resolutions. AVI, MKV, MOV, MP4, WMV, FLV. To... Read more

Latest Forum Discussions

See All

It Came From Canada: Angry Birds: Transf...
Anyone afraid that throwing Transformers into the Angry Birds mix would result in a Michael Bay-level of childhood pillaging can rest easy. While Rovio’s famous fowls may be a 21st century staple, Angry Birds: Transformers wears its affection for... | Read more »
Galaxy Trucker Review
Galaxy Trucker Review By Rob Thomas on September 30th, 2014 Our Rating: :: IN FOR THE LONG HAULiPad Only App - Designed for the iPad We got a great big convoy, rockin’ through the night… the endless night of outer space, that is.... | Read more »
Moon and Sun – children’s book Review
Moon and Sun – children’s book Review By Amy Solomon on September 30th, 2014 Our Rating: Moon and Sun is a fable-like children’s book with lush illustrations.   Developer: Marcio Monteiro Price: $3.99 Version: 1.0 App Reviewed on... | Read more »
Kairosoft Finally Brings The Pyraplex to...
Kairosoft Finally Brings The Pyraplex to iOS Posted by Jessica Fisher on September 30th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Yeti’s Parole Officer Review
Yeti’s Parole Officer Review By Jennifer Allen on September 30th, 2014 Our Rating: Universal App - Designed for iPhone and iPad Yeti’s Parole Officer proves that looks aren’t everything in this entertaining, if plain, piece of... | Read more »
Record Keeper and World Wide Words – Two...
Record Keeper and World Wide Words – Two New Final Fantasy Games Arrive on iOS in Japan Posted by Ellis Spice on September 30th, 2014 [ permalink ] | Read more »
iPollute Review
iPollute Review By Nadia Oxford on September 30th, 2014 Our Rating: :: iPOLLUTE, uPOLLUTEUniversal App - Designed for iPhone and iPad iPollute is a delightful-looking pollution simulator, though it’s a bit light on “game” content... | Read more »
This Week at 148Apps: September 22-26, 2...
Your Source For The Latest App Reviews   | Read more »
Kill Shot Review
Kill Shot Review By Jennifer Allen on September 29th, 2014 Our Rating: :: OCCASIONAL MISFIRESUniversal App - Designed for iPhone and iPad Kill Shot is often satisfying, but its more than pushy in-app purchases will leave you... | Read more »
It Came From Canada: Vainglory
I’m going to be straight you with folks. I don’t know much about MOBAs, and I’m certainly no professional. That means I don’t know how well Vainglory, the upcoming multiplayer online battle arena showcased in the most recent Apple keynote, compares... | Read more »

Price Scanner via MacPrices.net

MacBook Airs on sale for $100 off MSRP, start...
Best Buy has the new 2014 MacBook Airs on sale for $100 off MSRP on their online store. Choose free home shipping or free local store pickup (if available). Prices valid for online orders only, in-... Read more
Apple Releases OS X Mavericks bash Update 1.0...
Apple has released a patch update for OS X Mavericks users to address the recently-detected “Shellshock” security bug in BSD UNIX’s bash shell. Apple says only a few Mac users who had manually... Read more
Pivotal Payments Ready for Apple Pay – FlexPo...
Pivotal Payments, a provider of merchant services and global payment processing solutions, has announced its proprietary FlexPoint platform will support credit and debit transactions through Apple’s... Read more
iStabilizer Announces Tabarm — First Friction...
iStabilizer, a specialist in universal lightweight compact tripods, steady cams, dollies, mounts, and remotes for smartphones, tablets, and cameras, announced today the iStabilizer tabArm, the first... Read more
IStabilizer Flex Smartphone Tripod Wins Usa T...
iStabilizer, a specialist in universal lightweight compact tripods, steady cams, and other products for smartphones, tablets, and cameras, has announced today that its iStabilizer Flex smartphone... Read more
13-inch 2.8GHz Retina MacBook Pro on sale for...
B&H Photo has the new 2014 13″ 2.8GHz Retina MacBook Pro on sale for $1699.99 including free shipping plus NY sales tax only. They’ll also include free copies of Parallels Desktop and LoJack for... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has the new 2014 15″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only. They’ll also include free copies of Parallels Desktop... Read more
Get Down to Business On Your iPad With Free N...
Utah based Poem LLC has introduced Nexticy 1.0, a full-featured, affordable (Free) forms application for iPad. Nexticy makes it ‘way easy’ to create, store, retrieve and analyze paper-like forms of... Read more
13-inch Retina MacBook Pros on sale for $100...
Best Buy has 13-inch 2.6GHz Retina MacBook Pros on sale for $100 off MSRP on their online store. Choose free shipping or free local store pickup (if available). Prices are for online orders only, in-... Read more
Reports Outline Claimed 12-Inch Macbook Air D...
Blogger Jack March says that according to information he’s received from an anonymous “source familiar with Apple’s plans,” the next-generation MacBook Air will launch in mid-2015 and be available... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.