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

Duplicate Annihilator 5.7.5 - Find and d...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator... Read more
BusyContacts 1.0.2 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Capture One Pro 8.2.0.82 - RAW workflow...
Capture One Pro 8 is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 300 high-end cameras -- straight out of the box. It... Read more
Backblaze 4.0.0.872 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac.With unlimited storage available for $5 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Little Snitch 3.5.2 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Monolingual 1.6.4 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. If you use your computer in only one (human) language, you... Read more
CleanApp 5.0 - Application deinstaller a...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
Fantastical 2.0 - Create calendar events...
Fantastical is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event details... Read more
Cocktail 8.2 - General maintenance and o...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Skype 7.6.0.409 - Voice-over-internet ph...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more

Fast & Furious: Legacy's Creati...
| Read more »
N-Fusion and 505's Ember is Totally...
| Read more »
These are All the Apple Watch Apps and G...
The Apple Watch is less than a month from hitting store shelves, and once you get your hands on it you're probably going to want some apps and games to install. Fear not! We've compiled a list of all the Apple Watch apps and games we've been able to... | Read more »
Appy to Have Known You - Lee Hamlet Look...
Being at 148Apps these past 2 years has been an awesome experience that has taught me a great deal, and working with such a great team has been a privilege. Thank you to Rob Rich, and to both Rob LeFebvre and Jeff Scott before him, for helping me... | Read more »
Hands-On With Allstar Heroes - A Promisi...
Let’s get this out of the way quickly. Allstar Heroes looks a lot like a certain other recent action RPG release, but it turns out that while it’s not yet available here, Allstar Heroes has been around for much longer than that other title. Now that... | Read more »
Macho Man and Steve Austin Join the Rank...
WWE Immortals, by Warner Bros. Interactive Entertainment and WWE, has gotten a superstar update. You'll now have access to Macho Man Randy Savage and Steve Austin. Both characters have two different versions: Macho Man Randy Savage Renegade or Macho... | Read more »
Fearless Fantasy is Fantastic for the iF...
I actually had my first look at Fearless Fantasy last year at E3, but it was on a PC so there wasn't much for me to talk about. But now that I've been able to play with a pre-release version of the iOS build, there's quite a bit for me to talk... | Read more »
MLB Manager 2015 (Games)
MLB Manager 2015 5.0.14 Device: iOS Universal Category: Games Price: $4.99, Version: 5.0.14 (iTunes) Description: Guide your favorite MLB franchise to glory! MLB Manager 2015, officially licensed by MLB.com and based on the award-... | Read more »
Breath of Light (Games)
Breath of Light 1.0.1421 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1421 (iTunes) Description: Hold a quiet moment. Breath of Light is a meditative and beautiful puzzle game with a hypnotic soundtrack by... | Read more »
WWE WrestleMania Tags into the App Store
Are You ready to rumble? The official WWE WrestleMania app, by World Wrestling Entertainment, is now available. Now you can get all your WrestleMania info in one place before anyone else. The app offers details on superstar signings, interactive... | Read more »

Price Scanner via MacPrices.net

Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Samsung Galaxy S 6 and Galaxy S 6 edge U.S. P...
Samsung Electronics America, Inc. has announced the Galaxy S 6 and Galaxy S 6 edge will be available in the U.S. beginning April 10, with pre-orders being accepted now. “We have completely reimagined... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
The Apple Store has Apple Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.... Read more
Save up to $80 on iPad Air 2s, NY tax only, f...
 B&H Photo has iPad Air 2s on sale for $80 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $469.99 $30 off - 64GB iPad Air 2 WiFi: $549.99 $50 off - 128GB iPad... Read more
iMacs on sale for up to $205 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Färbe Technik Offers iPhone Battery Charge LI...
Färbe Technik, which manufactures and markets of mobile accessories for Apple, Blackberry and Samsung mobile devices, is offering tips on how to keep your iPhone charged while in the field: •... Read more
Electronic Recyclers International CEO Urges...
Citing a recent story on CNBC about concerns some security professionals have about the forthcoming Apple Watch, John Shegerian, Chairman and CEO of Electronic Recyclers International (ERI), the... Read more
Save up to $380 with Apple refurbished iMacs
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
Mac minis on sale for up to $75 off, starting...
MacMall has Mac minis on sale for up to $75 off MSRP including free shipping. Their prices are the lowest available for these models from any reseller: - 1.4GHz Mac mini: $459.99 $40 off - 2.6GHz Mac... Read more
College Student Deals: Additional $50 off Mac...
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through April 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more

Jobs Board

DevOps Software Engineer - *Apple* Pay, iOS...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*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
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
Lead *Apple* Solutions Consultant - Retail...
**Job Summary** Job Summary The Lead ASC is an Apple employee who serves as the Apple business manager and influencer in a hyper-business critical Reseller's store Read more
*Apple* Pay - Site Reliability Engineer - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.