TweetFollow Us on Twitter

External Windows 1
Volume Number:7
Issue Number:2
Column Tag:XCMD Corner

Related Info: Window Manager Event Manager

External Windows

By Donald Koscheka, Contributing Editor

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

External Windows

This month, we are going to take a comprehensive look at external window management in Hypercard 2.0. External windows are easy to work with and if you’ve been programming the Macintosh for any amount of time, you won’t have any trouble with them. If you’re a newcomer to the field, external windows are an excellent place to start as the core of an external window management system is the same as any Macintosh application -- the event loop.

Hypercard 2.0 supports external windows in a much more generous fashion than was available under Hypercard 1.x. For one thing, external windows can support callbacks so that you can interface the window directly to Hypercard which was not possible under Hypercard 1.x. External windows do not pre-empt the card, both Hypercard windows and external windows (let’s call them xwindoids) coexist quite nicely in HC2.0.

Windows in Hypercard 2.0 exist in one of two layers, the document layer and the floating layer. Palettes live in the floating layer. Windows in this layer never get activate events -- they are active at all times that they are visible. The toolbox call to Frontwindow() will always return a pointer to a floating window if any floating windows are visible. The frontmost document window will be reported throughout the Hypercard callback, FrontDocWindow().

The document layer is the standard Macintosh windowing environment. Documents behave like typical Macintosh windows, they respond to all standard Macintosh events as well as some Hypercard specific events.

Opening Windows

Listing 1, xwindoids.c, depicts an xcmd that creates a window in the document layer. The window is created by a call to the Hypercard callback, NewXWindow(). In order for Hypercard to add your window to its document or floating layer, you must open your window using this callback or its close cousin, GetNewXWindow() which opens a window from a resource template. You can still use NewWindow if you have some old xcmd that supports external windows, but windows created by directly calling the window manager will not get Hypercard events nor will they be able to make callbacks to Hypercard.

The prototype for these two new callbacks are:

/* 1 */

extern pascal WindowPtr NEWXWINDOW(XCmdPtr paramPtr, Rect *boundsRect, 
StringPtr title, Boolean visible, short procID, Boolean color, Boolean 

extern pascal WindowPtr GETNEWXWINDOW(XCmdPtr paramPtr, ResType templateType, 
short templateID, Boolean color, Boolean floating);

Both callbacks return a standard window manager WindowPtr so there is nothing new there. Being callbacks, both routines need to have the paramPtr passed in. Notice that Apple changed the name of the paramPtr struct form XCmdBlkPtr to XCmdPtr. The structure remains unchanged however.

For NewXWindow, the rectangle, title, visible and procID all correspond to the equivalent parameters in NewWindow(). Similarly, GetNewXWindow() gets passed the id of the resource window template. You have the option of opening color windows and of making them floating or document windows by assigning true or false for these parameters. Listing 1 opens a non-color document window.

XWindoids Events

The xcmd creates the window and does nothing more with the window for the time being. It returns to Hypercard which will subsequently call this very same xcmd with an xOpenEvt hypercard event. This is important because it represents a departure away from the way we are used to thinking about xcmds. When an xcmd creates a window, it is said to “own” that window. Any events that must be handled for that window will be sent to that xcmd. Thus, Hypercard will call upon the xcmd to handle events in a manner that is transparent to the rest of Hypercard.

We detect whether the xcmd is being sent an event by checking the paramCount field in the xcmd command block. By convention, if the number of parameters is less than 0, then we have an event. In this case, Hypercard passes us a pointer to a Hypercard event record in params[0] . The hypercard event record looks like this:

/* 2 */

typedef struct XWEventInfo *XWEventInfoPtr; 
struct XWEventInfo {
 EventRecord event;
 WindowPtr eventWindow;
 long eventParams[9];
 Handle eventResult;

The first field in the record is the standard Macintosh event manager event record. Its fields correspond to the normal usage of an event record. The next field is a pointer to the window that the event is meant for. This is provided for the case of xcmds that handle more than 1 window. Our xcmd handles only one window so we can use this field to point to that window rather than calling FrontWindow() which might return the wrong result (since it always passes a visible palette as the front window).

EventParams and eventResult are used to pass information about specific events to the xcmd. None of the events in xwindoids.c uses these fields so we’ll reserve their discussion for the future.

If paramCount is zero, we dispatch the parameter block to our event handler, in this case a routine called “HandleHCEvent”. HandleHCEvent must first dereference the hypercard event record so that all of its fields are accessible. Next, we set passFlag to true. I’m still trying to piece together the rules for this. It seems that you pass true back to hypercard to tell it to handle the event and false to tell it not to handle the event. If anyone can illuminate this better than that, I will be happy to publish your explanation as the use of this field in relation to events is only briefly discussed in the Hypercard 2.0 xcmd technical documentation. In the meantime, I’ve been using trial and error to get the value of passflag right for each event.

Once the event record is dereferenced, HandleHCEvent closely resembles the event processing switch of any generic Macintosh Application. This is good, you can port your code to Hypercard very quickly by using listing 1 as a template. There is no need to call getNextEvent or WaitNextEvent. Hypercard is taking each event and deciding in turn whether it needs to be dispatched to an external window. Keep in mind that in order for an xcmd to get events, it must have a window associated with it. This is not quite according to Hoyle but it will do. Rather than address each case in the switch, let’s follow the event processing in the order that the events will be called.

Upon opening a new window, the very first event to be called will be xOpenEvt. It is here that we allocate any private storage needed by the window. In the case of xwindoids.c, we will fill the window up with a text edit record just to show that we can do some editing in the window. We store the TextEdit record off the window’s refcon so that we can find it easily. Use any storage schema that you’re comfortable with. If you’re using Think C, A4 Globals will work okay here also, make sure that you set up A4 first. A quick sideline: Think compilers do an outstanding job of supporting the kinds of features that you’ll need to write non-A5 relative code. I use Think “C” or Think Pascal exclusively for writing xcmds because of the multi-segment support and the ability to set up my own environment based off register A4.

Note that I only show the window, which was created as invisible only after taking the xOpenEvt. I figure that it’s better not to show the window until Hypercard is ready to deal with it which is at xOpenEvt time. That way the window does stare back at me with that slack-jawed blank content region look while I’m waiting for Hypercard to tell me that it’s okay to start using it. We need to set passFlag to true on xOpenEvt to tell hypercard that we took the event. From here on out, we will get all events intended for this window.

The next event we get is the activateEvt. This is the standard event manager activate event and is only passed to Document windows. Floating windows are always active so they don’t get activate events. We first check to see if we’re going active or inactive. If the former, then we can activate our text edit record and advise Hypercard that our window now has the edit (or input) focus by calling BeginXWEdit. Once this callback is made, Hypercard will send all keydowns to us until one of two events occurs: our window becomes inactive or Hypercard tells us to give up edit by sending us the xGiveUpEditEvt event. In order to be Hypercard friendly, we need to be prepared to give up the edit focus at any time, Hypercard will tell us when, but we should be courteous and acknowledge the event if we have the edit focus.

Once we become the active window, we will get the update evt followed by any number of events until such time as our window is closed. If the user clicks on the goaway box, Hypercard will advise us that our window is closing. First, the window will go inactive. Next we will get the XWCloseEvt event. At this time, we should close down our internal data structures associated with the window (such as the TEHandle). In listing 1, I hide the window here also. There is no need to call closeWindow or otherwise deallocate the window structures, Hypercard will do that for you.

As you can see from listing 1, there are a lot of new Hypercard events to talk about and we will get to the rest of them in future columns. The rest of event handling is standard Macintosh stuff and seems to work just fine. Note that in the null event handler (default:) we need to adjust the cursor ourselves if the mouse is in the edit box. I found that unless you set passflag to false, Hypercard will set the cursor back to the arrow on you here resulting in a flickering cursor.

Handling mousedown events is little different than you might be accustomed to also. In the case of the goaway control, we do the usual tracking but instead of closing the window directly, we issue a callback, CLOSEXWINDOW, to hypercard in effect asking hypercard to close the window for us. Hypercard will respond that the window is ready to be closed by sending us back an XWCloseEvt at some time in the future. Between the CloseXWindow call and the XWCloseEvt event, the window is in limbo, it might make sense to hide the window here to give the user the sense that the window closed but I find that the latency between these events just isn’t long enough to worry about that.

Dragging the window seems to be handled directly by Hypercard so we don’t do anything with that event. I handle the incontent hits as if this were a normal application. It seems to work fine although you do need to set the passFlag to false after handling the mousedown or Hypercard will get confused.

Similarly, keyevents can be handled directly. Command keys are handled directly by Hypercard so there is no need to test to see if we have a menu key. Again, we set passflag to false to tell hypercard that we took this event. If we set passflag to true here, hypercard will try to handle the event going so far as to call us back with an XWGiveUpEdit event. That would be bad.

Listing 1 is by no means complete. It doesn’t handle scrolling or the grow box yet. You may want to begin your own investigations by adding these features to listing 1. In any event, happy hacking. If you discover anything that you would like to share with the rest of the Mac community, please drop me a line on AppleLink (D6845) or America On Line (AFC Donald).

Listing 1:

/* File: xwindoid.c*/
/* */
/* A sample XCMD for Hypercard*/
/* 2.0 that displays and handles*/
/* an external window.    */
/* */
/* Well-behaved XCMDs for HC2.0  */
/* will respond to the ! and ?*/
/* requests by returning version*/
/* and usage information  */
/* respectively. */
/* */
/* ----------------------------  */
/* ©1990, Donald Koscheka */
/* All Rights Reserved    */

 ANSI-A4-- standard “C” libraries assembled
 off of register A4
 HyperXLib-- Hypercard 2.0 callback library available from 
 Apple Computer, Inc.
 xwindoid.c (contents of listing 1)
 Set Project Type:
 Type == XCMD | XFCN
 Name == xwindoid
 id == -32768..32767
 xwindoid “?”
 xwindoid “!”
 put the result
 Put xwindoid( “?” )
 Put xwindoid( “!” )

#ifndef NIL
 #define NIL(void *)0L

#define ETX 0x03 
#define BS0x08   
#define TAB 0x09
#define LF0x0A
#define NEWLINE  0x0D
#define CR0x0D
#define LEFT_ARROW 0x1C
#define RIGHT_ARROW0x1D
#define UP_ARROW 0x1E
#define DOWN_ARROW 0x1F

/* Multifinder events and masks  */
#ifndef MouseMovedEvt

#ifndef SuspendResumeEvt
 #defineSuspendResumeEvt  0x01

#ifndef ResumeEvtMask

#ifndef ConvertScrapMask
 #defineConvertScrapMask  0x02

pascal void HandleHCEvent( XCmdPtr pp );

Handle  strToParam( str )
 char *str;
* Given a pointer to a string,
* copy that string into a handle
* and return the handle.
* The input and output strings
* are both null-terminated
 Handle outH = NIL;
 long len = 0;
 len = strlen( str );
 if( len )
 if( outH = NewHandle( len ) )
 BlockMove( str, *outH, len + 1 );
 return( outH );

pascal void main( pp )
 Handle answer = NIL;
 char   *str;
 long   len;
 TEHandle hTE;
 Rect   bounds;
 pp->returnValue = NIL;

 if( pp->paramCount < 0 ){
 HandleHCEvent( pp );
 if (pp->paramCount == 1){
 if ( **(pp->params[0]) == ‘!’ ){
 pp->returnValue = strToParam(“\pxwindoid XCMD, version 1.0, ©1990, Donald 
 if ( **(pp->params[0]) == ‘?’ ){
 pp->returnValue = strToParam(“\pSimple xwindoid handler.”);
 /* now open a window to play with */ = bounds.left = 0;
 bounds.bottom = 320;
 bounds.right = 500;
 wind = NEWXWINDOW( pp, &bounds, “\pSample Window”, FALSE, documentProc, 
 CenterWindow( wind );

pascal void HandleHCEvent( XCmdPtr pp )
* Handle events in our xWindows  
* returns true if the event was handled ok
 XWEventInfoPtr  ip= pp->params[0];
 short  windoPart;
 TEHandle hTE;
 Rect   bounds;
 Point  hit;
 char   theKey;
 short  extend;
 pp->passFlag = TRUE;/* seems to be more often the case */
 switch( ip->event.what ){
 case mouseDown:
 windoPart = FindWindow( ip->event.where, &whichWindow );
 if( whichWindow )
 switch ( windoPart ){
 case inGoAway:
 if (TrackGoAway( whichWindow, ip->event.where) ){
 CLOSEXWINDOW( pp,whichWindow );
 pp->passFlag = FALSE;

 case inDrag:
 /* handled by hypercard */
 case inGrow:
 case inContent:
 if (whichWindow == FrontWindow() ){
 GetPort( &oldPort );
 SetPort( ip->eventWindow );
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 hit = ip->event.where;
 GlobalToLocal( &hit );
 bounds = (*hTE)->viewRect;
 if( PtInRect( hit, &bounds ) ){
 extend = (short)ip->event.modifiers && shiftKey;
 TEClick( hit, extend, hTE);
 SetPort( oldPort );
 SelectWindow( whichWindow );

 pp->passFlag = FALSE;
 }/* window part */
 case mouseUp:
 case keyDown:
 case autoKey: 
 /* the command key will be handled by hypercard */
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 GetPort( &oldPort );
 SetPort( ip->eventWindow );
 theKey  = ip->event.message & 0xFF;
 switch( theKey ){
 case TAB:
 case ETX:
 case UP_ARROW:
 case BS:
 TEKey( theKey, hTE );
 }/* switch( theKey ) */
 SetPort( oldPort );
 pp->passFlag = FALSE;
 case activateEvt:
 if ( ip->event.modifiers & activeFlag ){
 BEGINXWEDIT( pp, ip->eventWindow );
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 TEActivate( hTE );
 ENDXWEDIT( pp, ip->eventWindow );
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 TEDeactivate( hTE );
 case updateEvt: 
 BeginUpdate( ip->eventWindow );
 DrawGrowIcon( ip->eventWindow );
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 bounds = (*hTE)->viewRect;
 TEUpdate( &bounds, hTE );
 EndUpdate( ip->eventWindow );
 case app4Evt:
 unsigned char *evtType = &(ip->event.message);
 switch( *evtType ){
 case MouseMovedEvt:
 case SuspendResumeEvt:

 case xOpenEvt:
 /* for illustrative purposes, we  */
 /* add a text edit field to the   */
 /* window*/
 SetPort( ip->eventWindow );
 bounds = ip->eventWindow->portRect; += 4;
 bounds.left +=4;
 bounds.bottom -= 16;
 bounds.right -= 16;
 hTE  = TENew( &bounds, &bounds );
 (*hTE)->txFont = courier;
 (*hTE)->txFace = 0;
 (*hTE)->txSize = 10;
 SetWRefCon( ip->eventWindow, (long)hTE );
 ShowWindow( ip->eventWindow );
 case xCloseEvt:
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 TEDispose( hTE );
 HideWindow( ip->eventWindow );
 case xGiveUpEditEvt:
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 TEDeactivate( hTE );

 case xEditUndo:
 case xEditCut:
 case xEditCopy:
 case xEditPaste:
 case xEditClear:
 GetPort( &oldPort );
 SetPort( ip->eventWindow );
 GetMouse( &hit );
 hTE    = (TEHandle)GetWRefCon( ip->eventWindow );
 bounds = (*hTE)->viewRect;
 if( PtInRect( hit, &bounds ) ){
 SetCursor( *GetCursor(iBeamCursor) );
 TEIdle( hTE );
 pp->passFlag = FALSE;
 SetPort( oldPort );
 }/* switch theEvent->what */

Community Search:
MacTech Search:

Software Updates via MacUpdate

macOS Server 5.3 - Quickly and easily tu...
macOS Server, designed for macOS and iOS devices, makes it easy to share files, schedule meetings, synchronize contacts, develop software, host your own website, publish wikis, configure Mac, iPhone... Read more
Merlin Project 4.2.0 - Project managemen...
Merlin Project is the leading professional project management software for OS X. If you plan complex projects on your Mac, you won’t get far with a simple list of tasks. Good planning raises... Read more
Skim 1.4.28 - PDF reader and note-taker...
Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. Skim includes many features and has a... Read more
RapidWeaver 7.3.2 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
Together 3.8.1 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Features Smart storage. With simple drag-and-drop... Read more
Apple MainStage 3.3 - Live performance t...
Apple MainStage makes it easy to bring to the stage all the same instruments and effects that you love in your recording. Everything from the Sound Library and Smart Controls you're familiar with... Read more
Apple iOS 10.3 - The latest version of A...
iOS 10 is the biggest release of iOS ever. A massive update to Messages brings the power of the App Store to your conversations and makes messaging more personal than ever. Find your route with... Read more
Postbox 5.0.12 - Powerful and flexible e...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
Apple Keynote 7.1 - Apple's present...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more
Apple Pages 6.1 - Apple's word proc...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more

Hearthstone celebrates the upcoming Jour...
Hearthstone gets a new expansion, Journey to Un'Goro, in a little over a week, and they'll be welcoming the Year of the Mammoth, the next season, at the same time. There's a lot to be excited about, so Blizzard is celebrating in kind. Players will... | Read more »
4 smart and stylish puzzle games like Ty...
TypeShift launched a little over a week ago, offering some puzzling new challenges for word nerds equipped with an iOS device. Created by Zach Gage, the mind behind Spelltower, TypeShift boasts, like its predecessor, a sleak design and some very... | Read more »
The best deals on the App Store this wee...
Deals, deals, deals. We're all about a good bargain here on 148Apps, and luckily this was another fine week in App Store discounts. There's a big board game sale happening right now, and a few fine indies are still discounted through the weekend.... | Read more »
The best new games we played this week
It's been quite the week, but now that all of that business is out of the way, it's time to hunker down with some of the excellent games that were released over the past few days. There's a fair few to help you relax in your down time or if you're... | Read more »
Orphan Black: The Game (Games)
Orphan Black: The Game 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dive into a dark and twisted puzzle-adventure that retells the pivotal events of Orphan Black. | Read more »
The Elder Scrolls: Legends is now availa...
| Read more »
Ticket to Earth beginner's guide: H...
Robot Circus launched Ticket to Earth as part of the App Store's indie games event last week. If you're not quite digging the space operatics Mass Effect: Andromeda is serving up, you'll be pleased to know that there's a surprising alternative on... | Read more »
Leap to victory in Nexx Studios new plat...
You’re always a hop, skip, and a jump away from a fiery death in Temple Jump, a new platformer-cum-endless runner from Nexx Studio. It’s out now on both iOS and Android if you’re an adventurer seeking treasure in a crumbling, pixel-laden temple. | Read more »
Failbetter Games details changes coming...
Sunless Sea, Failbetter Games' dark and gloomy sea explorer, sets sail for the iPad tomorrow. Ahead of the game's launch, Failbetter took to Twitter to discuss what will be different in the mobile version of the game. Many of the changes make... | Read more »
Splish, splash! The Pokémon GO Water Fes...
Niantic is back with a new festival for dedicated Pokémon GO collectors. The Water Festival officially kicks off today at 1 P.M. PDT and runs through March 29. Magikarp, Squirtle, Totodile, and their assorted evolved forms will be appearing at... | Read more »

Price Scanner via

13-inch MacBook Airs, Apple refurbished, in s...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.6GHz/8GB/128GB MacBook Air: $... Read more
12-inch Retina MacBooks on sale for $1199, sa...
B&H has 12″ 1.1GHz Retina MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1199 $100 off MSRP - 12″ 1.1GHz... Read more
Save up to $260 with Apple refurbished 12-inc...
Apple has Certified Refurbished 2016 12″ Retina MacBooks available for $200-$260 off MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $170 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 15″ 2.2GHz Retina MacBook Pro (MJLQ2LL/A) on sale for $1799.99 including free shipping plus NY sales tax only. Their price is $200 off MSRP. Read more
Save up to $160 with Apple refurbished 9-inch...
Apple has Certified Refurbished 9″ and 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 9″... Read more
Apple Chip Foundry TSMC To Begin A11 System-o...
Digitimes’ Steve Shen is reporting today that according to the Chinese-language Economic Daily News (EDN), chipmaker and major Apple supplier foundery Taiwan Semiconductor Manufacturing Company (TSMC... Read more
MacX MediaTrans 3.5 iOS Data Transfer Spring...
MacXDVD Software has announced general availability of the latest MacX MedTrans 3.5, featuring a new user interface (UI). MacX MediaTrans is ann iPhone manager that enables free data transfer between... Read more
Regular Price $19.95 DupeZap 4 Finder For OS...
Hyperbolic Software has announced the release of DupeZap 4.0.2, their modern duplicate finder developed exclusively for macOS. DupeZap 4 is an utility for Mac owners seeking to reclaim disk space... Read more
B-Eng Releases SSD Health Check for MVNe for...
Fehraltorf, Switzerland based B-Eng has announced the release and immediate availability of SSD Health Check for MVNe for MacBook Pro, their app that delivers important data and insights for MVNe... Read more

Jobs Board

Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492889BR** **Job Title:** Apple Mobile Master **Location Number:** 000886-Norwalk-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492472BR** **Job Title:** Apple Mobile Master **Location Number:** 000470-Seattle-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492562BR** **Job Title:** Apple Mobile Master **Location Number:** 000853-Jackson-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.