TweetFollow Us on Twitter

Jan 98 - Getting Started

Volume Number: 14 (1998)
Issue Number: 1
Column Tag: Getting Started

Event-Based Programming

by Dave Mark

How a Mac program communicates with the user

Over the last year or so, we've gotten a lot of feedback about the direction in which you want this column to head. Some folks want more coverage of Java, others PowerPlant and Rhapsody. But the biggest vote of all was a return, for a spell, to the basics. When I first started this column more than six years ago (For you old-timers, my son Daniel, who was born in these pages, is now 5-1/2), we plowed a path for beginners, covering the basics of working with the Mac Toolbox. Since then, we've explored a wide variety of topics and have covered a lot of ground.

Over the next few months, we're going to revisit some of that territory at the behest of a new generation of Mac programmer. We started with last month's column, which gave an updated answer to the question, "How do I get started with Mac programming?" This month, we'll revisit the concept of event-based programming.

Know someone interested in getting started with Mac programming? Hand them your copy of last month's MacTech and point them this way...

Event-Based Programming

Most the programs we've created together have one thing in common. Each performs its main function, then sits there waiting for a mouse click using this piece of code:

while ( ! Button() )
  ;

This chunk of code represents the only mechanism the user has to communicate with the program. In other words, the only way a user can talk to one of our programs is to click the mouse to make the program disappear! This month's program is going to change all that.

One of the most important parts of the Macintosh Toolbox is the Event Manager. The Event Manager tracks all user actions, translating these actions into a form that's perfect for your program. Each action is packaged into an event record and each event record is placed on the end of the application's event queue.

For example, when the user presses the mouse button, a mouseDown event record is created. The record describes the mouseDown in detail, including such information as the location, in screen coordinates, of the mouse when the click occurred, and the time of the event, in ticks (60ths of a second) since system startup. When the user releases the mouse button, a second event, called a mouseUp event is queued.

If the user presses a key, a keyDown event is queued, providing all kinds of information describing the key that was pressed. An autoKey event is queued when a key is held down longer than a pre-specified autoKey threshold.

Though there are lots of different events, this month we're going to focus on four of them: mouseDown, mouseUp, keyDown, and autoKey. Next month we'll look at some of the others.

Working With Events

Events are the lifeline between your user and your program. They let your program know what your user is up to. Programming with events requires a whole new way of thinking. Up until this point, our programs have been sequential. Initialize the Toolbox, load a WIND resource, show the window, draw in it, wait for a mouse click, then exit.

Figure 1. The main event loop flowchart.

Event programming follows a more iterative path. Check out the flowchart in Figure 1. From now on, our programs will look like this. First, we'll perform our program's initialization. This includes initializing the Toolbox, loading any needed resources, perhaps even opening a window or two. Once initialized, your program will enter the main event loop.

The Main Event Loop

In the main event loop, your program uses a Toolbox function named WaitNextEvent() to retrieve the next event from the event queue. Depending on the type of event retrieved, your program will respond accordingly. A mouseDown might be passed to a routine that handles mouse clicks, for example. A keyDown might be passed to a text handling routine. At some point, some event will signal that the program should exit. Typically, it will be a keyDown with the key sequence command-Q, a mouseDown with the mouse on the Quit menu item, or as the result of a Quit event sent by another program like the Finder. If If it's not time to exit the program yet, your program goes back to the top of the event loop and retrieves another event, starting the process all over again.

WaitNextEvent() returns an event in the form of an EventRecord struct:

struct EventRecord
{
  short   what;
  long    message;
  long    when;
  Point   where;
  short   modifiers;
};

The what field tells you what kind of event was returned. As I said before, this month we'll only look at mouseDown, mouseUp, keyDown, and autoKey events, though there are lots more. Depending on the value of the what field, the message field contains four bytes of descriptive information. when tells you when the event occurred, and where tells you where the mouse was when the event occurred. Finally, the modifiers field tells you the state of the control, option, command and shift modifier keys when the event occurred.

EventMaster

This month's program, EventMaster, displays four lines, one for each of the events we've covered so far. As EventMaster processes an event, it highlights that line. For example, Figure 2 shows EventMaster immediately after it processed a mouseDown event.

Figure 2. EventMaster in action.

EventMaster requires a single resource of type WIND. Create a folder called EventMaster in your Development folder. Next, open ResEdit and create a new resource file named EventMaster.rsrc inside the EventMaster folder.

Figure 3. The WIND resource specifications.

Create a new WIND resource according to the specs shown in Figure 3. Make sure the resource ID is set to 128 and the Close Box checkbox is checked. Select Set 'WIND' Characteristics from the WIND menu and set the window title to EventMaster. Quit ResEdit, saving your changes.

Running EventMaster

Launch CodeWarrior and create a new project based on the MacOS:C/C++:Basic Toolbox 68k stationary. Turn off the Create Folder check box. Name the project EventMaster.mcp and place it in your EventMaster folder. Remove SillyBalls.c and SillyBalls.rsrc from the project; we will not be using these files. From the Finder, drag and drop your EventMaster.rsrc file into the project window. You also can remove the ANSI Libraries group from the project, because we won't need them, either. Your project window should look something like Figure 4.

Figure 4. EventMaster project window.

Select New from the File menu and type this source code in the window that appears:

#include <Sound.h>

#define kBaseResID      128
#define kMoveToFront    (WindowPtr)-1L
#define kSleep          7

#define kRowHeight      14
#define kFontSize        9

#define kMouseDown      1
#define kMouseUp        2
#define kKeyDown        3
#define kAutoKey        4

/*************/
/* Globals   */
/*************/

Boolean    gDone;
short      gLastEvent = 0;



/***************/
/* Functions   */
/***************/

void  ToolBoxInit( void );
void  WindowInit( void );
void  EventLoop( void );
void  DoEvent( EventRecord *eventPtr );
void  HandleMouseDown( EventRecord *eventPtr );
void  DrawContents( void );
void  SelectEvent( short eventType );
void  DrawFrame( short eventType );

/******************************** main *********/

void  main( void )
{
  ToolBoxInit();
  WindowInit();
  
  EventLoop();
}

/*********************************** ToolBoxInit */

void  ToolBoxInit( void )
{
  InitGraf( &thePort );
  InitFonts();
  InitWindows();
  InitMenus();
  TEInit();
  InitDialogs( nil );
  InitCursor();
}

/******************************** WindowInit *********/

void  WindowInit( void )
{
  WindowPtr  window;
  
  window = GetNewWindow( kBaseResID, nil, kMoveToFront );
  
  if ( window == nil )
  {
    SysBeep( 10 );  /* Couldn't load the WIND resource!!! */
    ExitToShell();
  }
  
  SetPort( window );
  TextSize( kFontSize );
  
  ShowWindow( window );
}

/******************************** EventLoop *********/

void  EventLoop( void )
{    
  EventRecord    event;
  
  gDone = false;
  while ( gDone == false )
  {
    if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) )
      DoEvent( &event );
  }
}

/************************************* DoEvent *********/

void  DoEvent( EventRecord *eventPtr )
{
  switch ( eventPtr->what )
  {
    case mouseDown:
      SelectEvent( kMouseDown );
      HandleMouseDown( eventPtr );
      break;
    case mouseUp:
      SelectEvent( kMouseUp );
      break;
    case keyDown:
      SelectEvent( kKeyDown );
      break;
    case autoKey:
      SelectEvent( kAutoKey );
      break;
    case updateEvt:
      BeginUpdate( (WindowPtr)eventPtr->message );
      DrawContents();
      EndUpdate( (WindowPtr)eventPtr->message );
  }
}

/******************************** HandleMouseDown *********/

void  HandleMouseDown( EventRecord *eventPtr )
{
  WindowPtr  window;
  short      thePart;
  
  thePart = FindWindow( eventPtr->where, &window );
  
  if ( thePart == inGoAway )
    gDone = true;
}

/******************************** DrawContents *********/

void  DrawContents( void )
{
  short      i;
  WindowPtr  window;
  
  window = FrontWindow();
  
  for ( i=1; i<=3; i++ )
  {
    MoveTo( 0, (kRowHeight * i) - 1 );
    LineTo( window->portRect.right,
        (kRowHeight * i) - 1 );
  }
  
  MoveTo( 4, 9 );
  DrawString( "\pmouseDown" );
  
  MoveTo( 4, 9 + kRowHeight );
  DrawString( "\pmouseUp" );
  
  MoveTo( 4, 9 + kRowHeight*2 );
  DrawString( "\pkeyDown" );
  
  MoveTo( 4, 9 + kRowHeight*3 );
  DrawString( "\pautoKey" );
  
  if ( gLastEvent != 0 )
    DrawFrame( gLastEvent );
}

/************************************* SelectEvent ********/

void  SelectEvent( short eventType )
{
  Rect        r;
  WindowPtr  window;
  
  window = FrontWindow();
  r = window->portRect;
  
  if ( gLastEvent != 0 )
  {
    ForeColor( whiteColor );
    DrawFrame( gLastEvent );
    ForeColor( blackColor );
  }
  
  DrawFrame( eventType );
  
  gLastEvent = eventType;
}



/************************************* DrawFrame *********/

void  DrawFrame( short eventType )
{
  Rect        r;
  WindowPtr  window;
  
  window = FrontWindow();
  r = window->portRect;
  
  r.top = kRowHeight * (eventType - 1);
  r.bottom = r.top + kRowHeight - 1;
  
  FrameRect( &r );
}

Once the source code is typed in, save the file as EventMaster.c. Select Add Window from the Project menu to add EventMaster.c to the project. Select Run from the Project menu to run EventMaster.

When the EventMaster window appears, click the mouse in the window. The mouseDown line will highlight. When you let go of the mouse button, the mouseUp line will highlight. Try this a few times, till you can play the entire drum solo to "Wipeout" on your mouse.

Next, press a key or two on your keyboard (try any key except one of the modifier keys control, option, shift or command). The keyDown line will highlight. Now press the key and hold it down for a while. After a brief delay, the autoKey line will highlight.

Once you're done playing, click the mouse in the EventMaster window's close box to exit the program.

Walking Through the EventMaster Source Code

EventMaster starts off by including <Sounds.h> to access the SysBeep() system call. (SysBeep() used by be part of OSUtils.h, but Apple moved it to Sounds.h as part of Universal Interfaces 3.0.1, included with CodeWarrior Pro 2.) Next we define a series of constants. Some you know, some you don't. The new ones will be explained as they are used in the code.

#define kBaseResID      128
#define kMoveToFront    (WindowPtr)-1L
#define kSleep          7

#define kRowHeight      14
#define kFontSize      9

#define kMouseDown      1
#define kMouseUp        2
#define kKeyDown        3
#define kAutoKey        4

The global gDone starts off with a value of false. When the mouse is clicked in the window's close box, gDone will be set to true and the program will exit. gLastEvent keeps track of the last event that occurred, taking on a value of either kMouseDown, kMouseUp, kKeyDown, or kAutoKey. We do this so we can erase the old highlighting (if any) before we draw the new highlighting.

Boolean    gDone;
short      gLastEvent = 0;

As usual, our program includes a function prototype for all our functions.

/***************/
/* Functions   */
/***************/

void  ToolBoxInit( void );
void  WindowInit( void );
void  EventLoop( void );
void  DoEvent( EventRecord *eventPtr );
void  HandleMouseDown( EventRecord *eventPtr );
void  DrawContents( void );
void  SelectEvent( short eventType );
void  DrawFrame( short eventType );

main() starts by initializing the Toolbox and loading the WIND resource to build the EventMaster window.

/******************************** main *********/

void  main( void )
{
  ToolBoxInit();
  WindowInit();

Next, we enter the main event loop.

  EventLoop();
}

EventLoop() continuously loops on a call to WaitNextEvent(), waiting for something to set gDone to true. The first parameter to WaitNextEvent() tells you what kind of events you are interested in receiving. The constant everyEvent asks the system to send every event it handles.

The second parameter is a pointer to an EventRecord. The third parameter tells the system how friendly your application is to other applications running at the same time. Basically, the number tells the system how many ticks you are willing to wait before recieving the next event, allowing other applications to get some processing time. This number should be about 7 when the application is not busy with a processor intensive task. If the application were doing something where it needed as much processor time as possible (such as compressing a document), this value would be set to zero, but WaitNextEvent() would be called once every seven ticks to give time to the system to check other applications.

The last parameter specifies a home-base region for the mouse. If the mouse moves outside this region, the system will generate a special event, known as a mouse-moved event. Since we won't be handling mouse-moved events, we'll pass nil as this last parameter.

/******************************** EventLoop *********/

void  EventLoop( void )
{    
  EventRecord    event;
  
  gDone = false;
  while ( gDone == false )
  {

WaitNextEvent() will return true if it successfully retrieved an event from the event queue. In that case, we'll process the event by passing it to DoEvent().

    if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) )
      DoEvent( &event );
  }
}

WaitNextEvent() is described in detail in Inside Macintosh: Macintosh Toolbox Essentials, on page 2-85. If you get a chance, read chapter 2, which describes the Event Manager in detail. You might also want to refer to Chapter 4 in the 2nd edition of the Macintosh C Programming Primer.

DoEvent() switches on eventPtr->what, sending the appropriate constant to the routine SelectEvent(), which highlights the appropriate line in the EventMaster window.

/************************************* DoEvent *********/

void  DoEvent( EventRecord *eventPtr )
{
  switch ( eventPtr->what )
  {

In the case of a mouseDown, we also pass the event on to our HandleMouseDown() routine, which will check for a mouseDown in the window's close box.

    case mouseDown:
      SelectEvent( kMouseDown );
      HandleMouseDown( eventPtr );
      break;
    case mouseUp:
      SelectEvent( kMouseUp );
      break;
    case keyDown:
      SelectEvent( kKeyDown );
      break;
    case autoKey:
      SelectEvent( kAutoKey );
      break;

OK, I know I promised we were only going to handle four event types this month, but I couldn't help but sneak this one in here. An update event is generated by the system when the contents of your window need to be redrawn. We'll get to updateEvt next month. In the meantime, if you want to force this code to execute, try triggering your screen dimmer, or cover the EventMaster window with another window and then uncover it..

    case updateEvt:
      BeginUpdate( (WindowPtr)eventPtr->message );
      DrawContents();
      EndUpdate( (WindowPtr)eventPtr->message );
  }
}

HandleMouseDown() calls FindWindow() to find out in which window, and in which part of the window, the mouse was clicked.

/******************************** HandleMouseDown *********/

void  HandleMouseDown( EventRecord *eventPtr )
{
  WindowPtr  window;
  short      thePart;
  
  thePart = FindWindow( eventPtr->where, &window );

If the mouse was clicked in the close box (also known as the goaway box), set gDone to true.

  if ( thePart == inGoAway )
    gDone = true;
}

DrawContents() draws the contents of the EventMaster window. Notice that the highlighting routine DrawFrame() is only called if a previous event has been handled.

/******************************** DrawContents *********/

void  DrawContents( void )
{
  short      i;
  WindowPtr  window;
  
  window = FrontWindow();
  
  for ( i=1; i<=3; i++ )
  {
    MoveTo( 0, (kRowHeight * i) - 1 );
    LineTo( window->portRect.right,
        (kRowHeight * i) - 1 );
  }
  
  MoveTo( 4, 9 );
  DrawString( "\pmouseDown" );
  
  MoveTo( 4, 9 + kRowHeight );
  DrawString( "\pmouseUp" );
  
  MoveTo( 4, 9 + kRowHeight*2 );
  DrawString( "\pkeyDown" );
  
  MoveTo( 4, 9 + kRowHeight*3 );
  DrawString( "\pautoKey" );
  
  if ( gLastEvent != 0 )
    DrawFrame( gLastEvent );
}

SelectEvent() erases the old highlighting (if it existed) and then draws the new highlighting.

/************************************* SelectEvent   */

void  SelectEvent( short eventType )
{
  Rect        r;
  WindowPtr  window;
  
  window = FrontWindow();
  r = window->portRect;
  
  if ( gLastEvent != 0 )
  {
    ForeColor( whiteColor );
    DrawFrame( gLastEvent );
    ForeColor( blackColor );
  }
  
  DrawFrame( eventType );
  
  gLastEvent = eventType;
}

DrawFrame() draws the highlighting rectangle.

/************************************* DrawFrame *********/

void  DrawFrame( short eventType )
{
  Rect        r;
  WindowPtr  window;
  
  window = FrontWindow();
  r = window->portRect;
  
  r.top = kRowHeight * (eventType - 1);
  r.bottom = r.top + kRowHeight - 1;
  
  FrameRect( &r );
}

Some Homework

To understand more about events, read the Event Manager chapters in Inside Macintosh: Macintosh Toolbox Essentials. You may have noticed that EventMaster left a lot of room on the right side of each of its event lines. Use this space as a scratch pad, drawing information culled from the EventRecord each time you process an event.

As an example, try writing out the contents of the when and where fields. How about pulling the character and key codes out of the message field of a keyDown event. Think of EventMaster as an event playground. Play. Learn.

Next Month

Next month, we'll dig into some events designed specifically for the Window Manager: update and activate events. See you next month...

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Fallout Shelter pulls in ten times its u...
When the Fallout TV series was announced I, like I assume many others, assumed it was going to be an utter pile of garbage. Well, as we now know that couldn't be further from the truth. It was a smash hit, and this success has of course given the... | Read more »
Recruit two powerful-sounding students t...
I am a fan of anime, and I hear about a lot that comes through, but one that escaped my attention until now is A Certain Scientific Railgun T, and that name is very enticing. If it's new to you too, then players of Blue Archive can get a hands-on... | Read more »
Top Hat Studios unveils a new gameplay t...
There are a lot of big games coming that you might be excited about, but one of those I am most interested in is Athenian Rhapsody because it looks delightfully silly. The developers behind this project, the rather fancy-sounding Top Hat Studios,... | Read more »
Bound through time on the hunt for sneak...
Have you ever sat down and wondered what would happen if Dr Who and Sherlock Holmes went on an adventure? Well, besides probably being the best mash-up of English fiction, you'd get the Hidden Through Time series, and now Rogueside has announced... | Read more »
The secrets of Penacony might soon come...
Version 2.2 of Honkai: Star Rail is on the horizon and brings the culmination of the Penacony adventure after quite the escalation in the latest story quests. To help you through this new expansion is the introduction of two powerful new... | Read more »
The Legend of Heroes: Trails of Cold Ste...
I adore game series that have connecting lore and stories, which of course means the Legend of Heroes is very dear to me, Trails lore has been building for two decades. Excitedly, the next stage is upon us as Userjoy has announced the upcoming... | Read more »
Go from lowly lizard to wicked Wyvern in...
Do you like questing, and do you like dragons? If not then boy is this not the announcement for you, as Loongcheer Game has unveiled Quest Dragon: Idle Mobile Game. Yes, it is amazing Square Enix hasn’t sued them for copyright infringement, but... | Read more »
Aether Gazer unveils Chapter 16 of its m...
After a bit of maintenance, Aether Gazer has released Chapter 16 of its main storyline, titled Night Parade of the Beasts. This big update brings a new character, a special outfit, some special limited-time events, and, of course, an engaging... | Read more »
Challenge those pesky wyverns to a dance...
After recently having you do battle against your foes by wildly flailing Hello Kitty and friends at them, GungHo Online has whipped out another surprising collaboration for Puzzle & Dragons. It is now time to beat your opponents by cha-cha... | Read more »
Pack a magnifying glass and practice you...
Somehow it has already been a year since Torchlight: Infinite launched, and XD Games is celebrating by blending in what sounds like a truly fantastic new update. Fans of Cthulhu rejoice, as Whispering Mist brings some horror elements, and tests... | Read more »

Price Scanner via MacPrices.net

Verizon has Apple AirPods on sale this weeken...
Verizon has Apple AirPods on sale for up to 31% off MSRP on their online store this weekend. Their prices are the lowest price available for AirPods from any Apple retailer. Verizon service is not... Read more
Apple has 15-inch M2 MacBook Airs available s...
Apple has clearance, Certified Refurbished, 15″ M2 MacBook Airs available starting at $1019 and ranging up to $300 off original MSRP. These are the cheapest 15″ MacBook Airs for sale today at Apple.... Read more
May 2024 Apple Education discounts on MacBook...
If you’re a student, teacher, or staff member at any educational institution, you can use your .edu email address when ordering at Apple Education to take up to $300 off the purchase of a new MacBook... Read more
Clearance 16-inch M2 Pro MacBook Pros in stoc...
Apple has clearance 16″ M2 Pro MacBook Pros available in their Certified Refurbished store starting at $2049 and ranging up to $450 off original MSRP. Each model features a new outer case, shipping... Read more
Save $300 at Apple on 14-inch M3 MacBook Pros...
Apple has 14″ M3 MacBook Pros with 16GB of RAM, Certified Refurbished, available for $270-$300 off MSRP. Each model features a new outer case, shipping is free, and an Apple 1-year warranty is... Read more
Apple continues to offer 14-inch M3 MacBook P...
Apple has 14″ M3 MacBook Pros, Certified Refurbished, available starting at only $1359 and ranging up to $270 off MSRP. Each model features a new outer case, shipping is free, and an Apple 1-year... Read more
Apple AirPods Pro with USB-C return to all-ti...
Amazon has Apple’s AirPods Pro with USB-C in stock and on sale for $179.99 including free shipping. Their price is $70 (28%) off MSRP, and it’s currently the lowest price available for new AirPods... Read more
Apple Magic Keyboards for iPads are on sale f...
Amazon has Apple Magic Keyboards for iPads on sale today for up to $70 off MSRP, shipping included: – Magic Keyboard for 10th-generation Apple iPad: $199, save $50 – Magic Keyboard for 11″ iPad Pro/... Read more
Apple’s 13-inch M2 MacBook Airs return to rec...
Apple retailers have 13″ MacBook Airs with M2 CPUs in stock and on sale this weekend starting at only $849 in Space Gray, Silver, Starlight, and Midnight colors. These are the lowest prices currently... Read more
Best Buy is clearing out iPad Airs for up to...
In advance of next week’s probably release of new and updated iPad Airs, Best Buy has 10.9″ M1 WiFi iPad Airs on record-low sale prices for up to $200 off Apple’s MSRP, starting at $399. Sale prices... Read more

Jobs Board

Liquor Stock Clerk - S. *Apple* St. - Idaho...
Liquor Stock Clerk - S. Apple St. Boise Posting Begin Date: 2023/10/10 Posting End Date: 2024/10/14 Category: Retail Sub Category: Customer Service Work Type: Part Read more
*Apple* App Developer - Datrose (United Stat...
…year experiencein programming and have computer knowledge with SWIFT. Job Responsibilites: Apple App Developer is expected to support essential tasks for the RxASL Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.