TweetFollow Us on Twitter

Constructing Apps
Volume Number:1
Issue Number:3
Column Tag:C Workshop

Basics in Constructing Applications

By Robert B. Denny

Last month’s C Workshop presented an application “template”, a program shell which can be used as the basis of many kinds of applications. The template can be used with most C systems since there are no calls to library functions. The only external services used are native Mac toolbox traps.

This month, we’ll look at some of the basics in constructing applications, including the tricky area of servicing desk accessories properly. If you have access to last month’s C Workshop, you can refer to the template application’s code for examples. It’s not necessary, though.

Common Requirements

Most applications share several common requirements. These are:

• Overall control is via the menu bar and pull-down menus.

• Detail control and input uses both the mouse and the keyboard.

• Multiple instances of multiple types of windows serve as user interfaces.

• All desk accessories must be usable during execution of the application, within the limits of available memory.

These requirements, combined with the Macintosh operating system, imply the overall application setup and control structure described below.

Applications should begin by initializing all of the system services that it intends to use. At a minimum, all applications should call InitGraf(), InitWindows(),InitFonts(), InitMenus(), InitDialogs() and TEInit(). Some desk accessories use dialogs, which in turn use TextEdit.

Menu Setup

Any application that supports desk accessories must support a menu bar with at least the “Apple”, “File” and “Edit” menus. These menus must be present as required by the Macintosh User Interface Guidelines, and desk accessories assume that they are present. Moreover, the “File” and “Edit” menu options must also conform to the User Interface Guidelines. Desk accessories make assumptions as to the order and meaning of options in these menus.

The “Apple” menu must be set up to contain the desk accessories for selection and opening. Your application must do this explicitly by first creating the menu then adding the desk accessories via the AddResMenu() service. For example:

MenuHandle mh;
 ...
InsertMenu(mh = GetMenu(1), 0);
AddResMenu(mh, ‘DRVR’);
 ...
DrawMenuBar();

In the example, GetMenu() loads the menu resource whose ID = 1 and returns a handle to it, which gets stored in mh. InsertMenu() then adds the menu to the menu bar. Next, AddResMenu() appends the names of all resources of type ‘DRVR’ to the menu. Desk accessories are “drivers” to the current Mac operating system, hence have the resource type of ‘DRVR’. Real drivers have names beginning with ‘.’ or ‘%’ and will not get added to the menu.

The “File” menu is not used (yet) by any of the standard desk accessories. It is up for grabs, though, and should follow the User Interface Guidelines. That is, the items should follow the order:

 New
 Open...
 Close
 Save
 Save as...
 ------
 Page Setup
 Print...
 ------
 Quit

Desk accessories are free to assume that the ordering (and therefore numbering) of menu items in the “File” menu conforms to the above.

The “Edit” menu is used by the Note Pad and other desk accessories. Again, the layout of the menu must follow the user interface guidelines, namely:

 Undo
 ------
 Copy
 Cut
 Paste
 ------
 Show Clipboard

To reiterate, the leftmost three menus must conform to the Macintosh User Interface Guidelines stated in Inside Macintosh if the application is to support desk accessories.

The Event Loop

The single most important character- istic of a Macintosh application is that it is event-driven. Most Mac applications have an “event loop” as their outermost control structure. Following initializa- tion, the application does something like:

while(TRUE)
 {
 SystemTask();
 if(!GetNextEvent(-1, &event))
 continue;
 switch(event.what)
 {

 ... cases for each event type
 ... our application handles

 default:  /* Junk other events */
 }
 }

It is vitally important to understand the event loop. Most trips around the loop circle back at the continue statement that gets executed if GetNextEvent() returns FALSE, meaning that there is no event for us to handle. In future versions of the Macintosh operating system which support multitasking, GetNextEvent() will probably return control to the scheduler, giving other tasks CPU time until an event occurs for the caller.

In any case, when an event for us does occur, GetNextEvent() returns TRUE and fills in our event record with information describing the nature of the event. In C, the event record can be defined as follows:

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

where the type Point is some mapping of the QuickDraw “point”, an ordered pair of 16-bit coordinates.

Control passes to the switch() statement, which dispatches to the event handling function appropriate for the event type. For example, an event type of mouseDown would dispatch to the function that handles mouse clicks.

In the example shown, the value for the first parameter to GetNextEvent() is -1. This parameter is the event mask, and in this case, it is set to “get” all types of events. The switch() statement should have case sections for each event type that the application explicitly handles. Other types of events use the default case, which does nothing.

If the event mask parameter specifies a subset of event types, those not specified will remain on the event queue for possible later processing. This may be needed for applications which use a certain event type to trigger processing of earlier events of other types not normally processed. This is tricky, though, and can be the source of some obscure bugs. Also, unprocessed events on the queue take up valuable memory space.

If that isn’t enough, there’s a system- wide event mask that controls what event types are recognized and queued. Your application can disable the queueing of certain event types by calling the SetEventMask() service. If your applica- tion doesn’t process certain event types, you should disable them in the system event mask. This prevents wasting valuable event queue memory space with unprocessed event records.

The bottom line is ... call GetNextEvent() with an event mask of everyEvent (-1) to dequeue all event types, then let the default case dispose of the events you aren’t interested in.

Just prior to calling GetNextEvent(), notice the call to SystemTask(). This Mac system service causes control to pass to each open desk accessory, in turn, then back to the caller. Normally, one call at the beginning of the event loop is sufficient to give desk accessories the time they need. If you have any places in your application where you “spin your wheels”, consider calling SystemTask() to help waste some time.

In a multi-tasking version of the Mac, SystemTask() will probably do nothing. Rather, control will be given to the task only when there is a live event for that task. Timer services will be provided for passing control back to the scheduler (and other tasks) when a synchronous delay is needed in the current task.

The event loop is the fundamental control structure of a Macintosh applica- tion. If you haven’t studied The Event Manager: A Programmer’s Guide, a chapter in Inside Macintosh, you should take the time now to do so.

Mouse-Down Events

Any application which supports desk accessories must handle mouse-down events. A mouse click in a desk accessory window gets passed as an event to the application. This quirk in the Mac system architecture requires the application to determine whether the click was in a desk accessory window or in one of its own windows. I should mention that this approach to click handling minimizes the uncontrollable overhead in the operating system for applications which need every available CPU cycle and which do not support desk accessories (whew!).

So, if you want to support desk accessories, your application must detect and process mouse-down events. If you detect a mouse click, first call the Window Manager function FindWindow() to find out where the cursor was when the mouse button was clicked.

If FindWindow() returns the predefined constant inSysWindow, it means that the cursor was in a desk accessory window when the mouse was clicked. If this is the case, call the Desk Manager function SystemClick(). This passes control back to the operating system service which handles desk accessory windows.

Other returns from FindWindow() indicate mouse clicks in windows (including what “part” of the window) or the menu bar, or out in “no man’s land”, the desktop background. We’ll discuss window handling in a future C Workshop. If the click is in the menu bar, then our application must dispatch to a menu handler, another necessity if we are to handle desk accessories.

Menu Selections

If the mouse click is “in the Menu Bar”, then our application must first determine the selected menu number and the item number in that menu, then dispatch accordingly. First, call the MenuSelect() service to get a longword containing both the menu number and the item number in that menu, then use HiWord() and LoWord() to split them up:

 unsigned short menu_id, item_no;
 unsigned long result;
 unsigned short HiWord(), LoWord();
 unsigned long MenuSelect();
 ...
 result = MenuSelect(&event.where);
 menu_id = HiWord(result);
 item_no = LoWord(result);

Then use nested switch() statements to dispatch based on the menu and item selected.

If the “Apple” menu has the desk accessories, your application must activate a selected accessory. If the menu selected is the “Apple” menu, and you have determined that the selection was indeed an accessory, then you simply call OpenDeskAcc() with the name of the menu item (the desk accessory name). The latter can be obtained by calling GetItem() with the menu item number.

The “Edit” menu must also be handled specially if desk accessories such as the Note Pad are to be supported properly. Before trying to dispatch to your own edit-handling functions, you must call the SystemEdit() service. If it returns FALSE, then dispatch to your own function. If it returns TRUE, however, then the menu selection was made while an editing desk accessory was open. The desk accessory handled (used) the request; you must ignore it.

If you haven’t yet studied the The Desk Manager: A Programmer’s Guide, a section of Inside Macintosh, then you should do so now. It’s required reading for programmers who are developing applications which must support desk accessories.

Final Words: Resources Versus Static Data

I’d like to finish up this month’s C Workshop with some thoughts on the use of resources in C programs. Pascal has no facilities for statically initializing data structures. Therefore, Pascal program- mers have no choice but to load static data via the resource mechanism if they are to avoid ugly space-consuming “initialization segments”. You should carefully consider the tradeoffs before deciding whether to make a particular data structure static in your program or to place it in a resource.

Any data that is designed to be tailored after building the application belongs in a resource. Same with large data struc- tures that are used infrequently and can be “purged” from the heap. They too should go in a resource.

It’s my feeling that anything else belongs in your application’s static data area if you can affored the room. Why? The use of resources can slow down your application markedly. On 128K systems, heap space is fragmented by frequent resource manager activity, causing garbage collection cycles and purges to disk. Reading in of resources to initialize static data is far slower than having them present in your application’s address space when it is loaded. Last but not least, it is difficult to maintain programs which contain constants that depend on the contents of resources. For example, the numbering of menu items must track across the C code and the RMaker source as well. As a C programmer, you have a choice.

Author’s Note

During the last couple of months, this author has received some comments regarding bias toward a particular C language system. I feel that a few explanatory words are in order.

It is not the present editorial policy of MacTech to review software products, or otherwise make comparisons or recommendations. There are many Mac publications providing this service. This publication is devoted to providing meaningful technical information for serious programmers. Each developer must decide for himself the system that best meets his requirements.

My philosophy of teaching strongly emphasizes both reading and writing. Programs provided in this column are intended to serve as “reading material”. In the interest of completeness, I feel that the particular C system used to implement a program should be part of the program’s documentation.

I do not endorse any C language system. There are many C systems on the market at this time, and more are appearing every month. Each of these systems has it’s own library and interface to the native Macintosh environment.

In order to minimize the dependence on a particular C system, the example programs given in this column will use a minimum of library support. The template program shown in the October 1984 edition has no library dependency at all.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Tor Browser 11.5.8 - Anonymize Web brows...
Using Tor Browser you can protect yourself against tracking, surveillance, and censorship. Tor was originally designed, implemented, and deployed as a third-generation onion-routing project of the U.... Read more
Alarm Clock Pro 15.0 - $19.95 (91% off)
Alarm Clock Pro isn't just an ordinary alarm clock. Use it to wake you up in the morning, send and compose e-mails, remind you of appointments, randomize the iTunes selection, control an internet... Read more
Google Chrome 107.0.5304.121 - Modern an...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
calibre 6.9.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Safari Technology Preview 16.4 - The new...
Safari Technology Preview contains the most recent additions and improvements to WebKit and the latest advances in Safari web technologies. And once installed, you will receive notifications of... Read more
FileZilla 3.62.2 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. The FileZilla Client not only supports FTP, but also FTP over TLS... Read more
djay Pro 4.0.13 - Transform your Mac int...
djay Pro provides a complete toolkit for performing DJs. Its unique modern interface is built around a sophisticated integration with iTunes and Spotify, giving you instant access to millions of... Read more
Opera 93.0.4585.21 - High-performance We...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
AppCleaner 3.6.6 - Uninstall your apps e...
AppCleaner allows you to uninstall your apps easily. It searches the files created by the applications and you can delete them quickly. Supports macOS Ventura. Fixed an issue causing failed updates... Read more
QuickBooks 21.0.7.1248 - Financial manag...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more

Latest Forum Discussions

See All

‘Top Hunter Roddy & Cathy’ Review –...
The NEOGEO is generally characterized by, with only a few notable exceptions, fighting games and Metal Slug. Within a couple of years of its launch, the vast majority of the output on the console seemed to be mining (quite successfully) a few... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for November 28th, 2022. In today’s article, we’ve got a pair of reviews to check out. Full reviews of Pokemon Scarlet and Violet and The Oregon Trail are waiting for you to read. There’... | Read more »
‘OPUS: Echo of Starsong’ Interview: Port...
With OPUS: Echo of Starsong ($8.99) having finally launched on iOS after hitting PC and consoles, I had a chance to talk to Scott Chen who is the co-founder and executive producer of Sigono. In our chat, I touched on topics like game subscription... | Read more »
Best iPhone Game Updates: ‘Rush Rally 3’...
Hello everyone, and welcome to the week! It’s time once again for our look back at the noteworthy updates of the last seven days. As November breaths its last, the holiday season is right around the corner. That means we should start seeing more... | Read more »
‘Total Football’ is an Arcade-Style Socc...
GALA SPORTS recently launched its brand new soccer title, Total Football, and, true to its name, it is a pure arcade-style soccer game in the same vein as FIFA Mobile and PES Mobile. It also features official licensing from FIFPro and Manchester... | Read more »
Genshin Impact will recieve two new char...
HoYoverse has announced that Genshin Impacts version 3.3 will be arriving on December 7th. Titled All Senses Clear, All Existence Void, the update will bring two powerful new characters and a brand new card-based minigame. [Read more] | Read more »
‘Wreckfest’ Mobile Compared With Console...
HandyGames’ mobile version of Bugbear’s demolition derby-style racer Wreckfest ($9.99) released on iOS and Android recently, and we featured it as our Game of the Week. | Read more »
Black Friday Deals Here – The TouchArcad...
After taking a couple of weeks off we return on this glorious Black Friday with another episode of The TouchArcade Show. We get into a big discussion about virtual assistants like Alexa, Siri, and Google, and their place in the greater smarthome... | Read more »
TouchArcade Game of the Week: ‘Station 1...
I’m a big fan of Glitch Games and their unique brand of point-and-click adventure/escape room/puzzle games, and while they’re a tiny outfit and there’d typically be a couple years gap in-between their new releases, they were always worth the wait.... | Read more »
SwitchArcade Round-Up: ‘Super Lone Survi...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for November 25th, 2022. Today we look at the remaining releases for the week, and I’ll be honest with you: it’s not a great assortment. Still, there are at least a couple of things... | Read more »

Price Scanner via MacPrices.net

Cyber Monday: 24″ Apple M1 iMacs for $150 off...
Amazon has Apple’s 24″ M1 iMacs on Black Friday sale for $150 off MSRP. Their prices are currently the lowest available for new iMacs among the Apple retailers we track: – 24″ M1 iMacs (8-Core CPU/7-... Read more
Cyber Monday Sale: 25% off Apple MagSafe acce...
Apple retailers are offering MagSafe accessories for up to 25% off MSRP for Cyber Monday. Here are the best deals available, currently from Verizon and Amazon: (1) Verizon has Apple MagSafe Chargers... Read more
Cyber Monday Sale: Apple AirPods for up to $1...
Looking for Apple AirPods, AirPods Pro, or AirPods Max this Cyber Monday? Look no further than our Apple AirPods Price Tracker. We track prices from 20+ Apple retailers and update the tracker... Read more
Final day for Apple’s Black Friday/Cyber Mond...
CYBER MONDAY Apple’s four day Black Friday/Cyber Monday 2022 event is now live and will run from November 25, 2022 to November 28, 2022 (ends today!). Receive a free $100-$250 Apple Gift Card with... Read more
Cyber Monday: Apple 13″ M2 MacBook Airs for $...
Apple retailers have posted their Cyber Monday prices on 13″ MacBook Airs. Take up to $200 off MSRP on M2-powered Airs with these sales with prices starting at only $1049. Free shipping is available... Read more
The best Cyber Monday iPhone sale? This $500...
If you switch to Xfinity Mobile and open a new line of service, they will take $500 off the price of a new iPhone, no trade-in required. This is the best no trade-in Cyber Monday Apple iPhone 14 deal... Read more
Cyber Monday Sale: Apple 16″ MacBook Pros for...
Amazon is offering $500 off MSRP discounts on Apple 16″ MacBook Pros with M1 Pro CPUs as part of their Cyber Monday sale. Their prices are the lowest available for these models from any Apple... Read more
Cyber Monday Sale: Apple 14″ MacBook Pros for...
Amazon is offering $300-$500 off MSRP discounts on Apple 14-inch MacBook Pros with M1 Pro CPUs as part of their Cyber Monday sale. Their prices are the lowest available for these models from any... Read more
Cyber Monday Sale: Apple Watch Ultra for $60...
Amazon has Apple Watch Ultra models (Alpine Loop, Trail Loop, and Opean Bans) on sale for $60 off MSRP as part of their Cyber Monday sale, each including free shipping, reducing the price for an... Read more
Cyber Monday MacBook Sale: 13″ M1 Apple MacBo...
Amazon has Apple 13″ M1 MacBook Airs back on sale for $200 off MSRP, starting at only $799, for Cyber Monday 2022. Their prices are the lowest available for new MacBooks this Cyber Monday. Stock may... Read more

Jobs Board

*Apple* Electronic Repair Technician - PlanI...
…a highly motivated individual to join our Production Department as an Apple Electronic Repair Technician. The computer repair technician will diagnose, assemble, Read more
Product Manager II - *Apple* - DISH (United...
…you will be doing We seek an ambitious, data-driven thinker to assist the Apple Product Development team as our new Retail Wireless division continues to grow and Read more
Staff Engineer 5G Protocol, *Apple* - DISH...
…metrics. Essential Functions and Responsibilities for a Staff Engineer 5G protocol( Apple ) Knowledge of 5G and 4G/LTE protocols and system architectures Experience 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
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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.