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 *

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

DiskCatalogMaker 6.4.12 - Catalog your d...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast. Finder-like intuitive look and feel. Super-fast search algorithm. Can compress catalog data... Read more
Macs Fan Control 1.3.0.0 - Monitor and c...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
Lyn 1.5.11 - Lightweight image browser a...
Lyn is a lightweight and fast image browser and viewer designed for photographers, graphic artists and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it... Read more
NeoOffice 2014.11 - Mac-tailored, OpenOf...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
LaunchBar 6.4 - Powerful file/URL/email...
LaunchBar is an award-winning productivity utility that offers an amazingly intuitive and efficient way to search and access any kind of information stored on your computer or on the Web. It provides... Read more
Remotix 3.1.4 - Access all your computer...
Remotix is a fast and powerful application to easily access multiple Macs (and PCs) from your own Mac. Features Complete Apple Screen Sharing support - including Mac OS X login, clipboard... Read more
DesktopLyrics 2.6.6 - Displays current i...
DesktopLyrics is an application that displays the lyrics of the song currently playing in "iTunes" right on your desktop. The lyrics for the song have to be set in iTunes; DesktopLyrics does nothing... Read more
VOX 2.5.1 - Music player that supports m...
VOX is a beautiful music player that supports many filetypes. The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all... Read more
NetNewsWire 4.0.0 - RSS and Atom news re...
NetNewsWire is the best way to keep up with the sites and authors you read most regularly. Let NetNewsWire pull down the latest articles, and read them in a distraction-free and Mac-like way. Native... Read more
MacUpdate Desktop 6.0.6 - Search and ins...
MacUpdate Desktop 6 brings seamless 1-click installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on macupdate.... Read more

Biz Builder Delux (Games)
Biz Builder Delux 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: Ah, there's nothing like the rhythmic bustle of a burgeoning business burg... especially when you're the one building it... | Read more »
Auroch Digital is Bringing Back Games Wo...
| Read more »
Carbo - Handwriting in the Digital Age...
Carbo - Handwriting in the Digital Age 1.0 Device: iOS Universal Category: Productivity Price: $3.99, Version: 1.0 (iTunes) Description: | Read more »
Draggy Dead (Games)
Draggy Dead 1.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.1 (iTunes) Description: Ditch your dead end job and take up a rewarding career in Grave Robbing today!Guide the recently deceased to a fun filled life of... | Read more »
Bad Dinos (Games)
Bad Dinos 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: | Read more »
The Apple Watch isn't Great as a Fi...
| Read more »
Show the World What You See With Stre.am...
Live broadcasting is getting popular on mobile devices, which is why you can now get Stre.am, by Infinite Takes. [Read more] | Read more »
PhotoTime's 2.1 Update Adds Apple W...
The latest PhotoTime update is adding even more functionality to the handy photo organizing app. Yep, including Apple Watch support. [Read more] | Read more »
Oh My Glob! Adventure Time Puzzle Quest...
Finn and Jake are taking over D3 Go!'s popular puzzle game series in the upcoming Adventure Time Puzzle Quest. [Read more] | Read more »
Earthcore: Shattered Elements - Tips, Tr...
At first glance, Earthcore: Shattered Elements seems like a rather simple card-battling game. Once you’re introduced to skills that will change quite a bit. Even more so once you start to acquire hero cards. But it’s not so complicated that we... | Read more »

Price Scanner via MacPrices.net

OtterBox Maximizes Portability, Productivity...
From the kitchen recipe book to the boarsroom presentation, the OtterBox Agility Tablet System turns tablets into one of the most versatile pieces of handheld technology available. Available now, the... Read more
Launch of New Car App Gallery and Open Develo...
Automatic, a company on a mission to bring the power of the Internet into every car, has announced the launch of the Automatic App Gallery, an app store for nearly every car or truck on the road... Read more
Memorial Day Weekend Sale: 13-inch 1.6GHz Mac...
Best Buy has the new 13″ 1.6GHz/128GB MacBook Air on sale for $849 on their online store this weekend. Choose free shipping or free local store pickup (if available). Sale price for online orders... Read more
Memorial Day Weekend Sale: 27-inch 3.5GHz 5K...
Best Buy has the 27″ 3.5GHz 5K iMac on sale for $2099.99 this weekend. Choose free shipping or free local store pickup (if available). Sale price for online orders only, in-store prices may vary.... Read more
Sale! 16GB iPad mini 3 for $349, save $50
B&H Photo has the 16GB iPad mini 3 WiFi on sale for $349 including free shipping plus NY sales tax only. Their price is $50 off MSRP, and it’s the lowest price available for this model. Read more
Price drop on 2014 15-inch Retina MacBook Pro...
B&H Photo has dropped prices on 2014 15″ Retina MacBook Pros by $200. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799.99 save $200 - 15″ 2.5GHz... Read more
With a Mission to Make Mobile Free, Scratch W...
Scratch Wireless, claiming to be the world’s first truly free mobile service, has announced the availability of a new Scratch-enabled Android smartphone, the Coolpad Arise. The smartphone is equipped... Read more
First-Ever Titanium Alloy Curved iPhone 6 Scr...
One of the most common problems with mobile phones is damage to the screens. The slightest drop can cause a dreaded spider web of gashes and cracks in the glass panel surface that can cost $hundreds... Read more
Preorder new 12-inch MacBook, $10 off, save o...
Adorama has new 12″ Retina MacBooks available for preorder for $10 off MSRP including free shipping plus NY & NJ sales tax only. For a limited time, Adorama will include a free Apple USB-C to USB... Read more
Will iOS 9 Finally Bring Productivity Friendl...
Ah, the irony. From its original announcement in 2010, Apple has doggedly insisted that the iPad remain “simple,” thus arbitrarily limiting its considerable potential as a content creation and... 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
Architect / Senior Software Engineer, *Apple...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Pay Support Readiness Project Manage...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.