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

Apple Remote Desktop Client 3.9 - Client...
Apple Remote Desktop Client is the best way to manage the Mac computers on your network. Distribute software, provide real-time online help to end users, create detailed software and hardware reports... Read more
Art Text 3.2.2 - $49.99
Art Text is graphic design software specifically tuned for lettering, typography, text mockups and various artistic text effects. Supplied with a great variety of ready to use styles and materials,... Read more
WhatRoute 2.0.15 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Sparkle 2.1.1 - $79.99
Sparkle will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more
Dash 4.0.1 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
TextSoap 8.3.2 - Automate tedious text d...
TextSoap can automatically remove unwanted characters, fix up messed up carriage returns, and do pretty much anything else that we can think of to text. Save time and effort. Be more productive. Stop... Read more
Apple Remote Desktop 3.9 - Remotely cont...
Apple Remote Desktop is the best way to manage the Mac computers on your network. Distribute software, provide real-time online help to end users, create detailed software and hardware reports, and... Read more
Paragraphs 1.1.4 - Writing tool just for...
Paragraphs is an app just for writers. It was built for one thing and one thing only: writing. It gives you everything you need to create brilliant prose and does away with the rest. Features... Read more
Amazon Chime 4.0.5528 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more
Apple Final Cut Pro X 10.3.2 - Professio...
Apple Final Cut Pro X is a professional video editing solution.Completely redesigned from the ground up, Final Cut Pro adds extraordinary speed, quality, and flexibility to every part of the post-... Read more

Blasty Bubs is a colorful Pinball and Br...
QuickByte Games has another arcade treat in the works -- this time it's a mishmash of brick breaking and Pinball mechanics. It's called Blasty Bubs, and it's a top down brickbreaker that has you slinging balls around a board. [Read more] | Read more »
Corsola and Heracross are the new region...
Generation 2 finally launched in Pokémon GO, unleashing a brand new batch of Pokémon into the wild. Even before the update went live people were speculating on how to catch elusive Pokémon like the legendary "dogs", Unknown, and whether or not... | Read more »
The Warlock of Firetop Mountain (Games)
The Warlock of Firetop Mountain 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: An epic adventure through a mysterious mountain filled with monsters, magic and mayhem! “...it looks downright... | Read more »
Fantasy MMORPG MU Origin’s receives a hu...
Developer Webzen are looking to take their highly popular fantasy battler MU Origin to the next level this month, with its most ambitious overhaul yet. The latest update introduces the long sought after Server Arena, new treasure dungeons, and much... | Read more »
RPG Djinn Caster (Games)
RPG Djinn Caster 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: SPECIAL PRICE 38% OFF(USD 7.99 -> USD 4.99)!!!A Fantasy Action RPG of far foreign lands! Summon the Djinns and rise to... | Read more »
Alto's Odyssey gets its first trail...
There's finally video evidence of Alto's Odyssey, the follow up to the 2015 App Store hit, Alto's Adventure. It looks just as soothing and atmospheric as Alto's last outing, but this time players will be journeying to the desert. Whereas Alto's... | Read more »
Last week on Pocket Gamer
What’s going on in the wider world of portable gaming? Each week we ask that question of our sister website Pocket Gamer. The PG team covers iOS gaming, just like 148Apps, but it also strays into the world of Android games and handheld consoles... | Read more »
Pokémon GO Generation 2 evolution guide
At long last, Niantic Labs finally unleashed the Generation 2 Pokémon into the wild. Pokémon GO trainers are scrambling to grab up this new set of 80 Pokémon. There are some special new tricks required to catch all of these new beasties, though.... | Read more »
The best new games we played this week
It feels as though the New Year got off to a creaking start as far as mobile games go, but that's changed over the past few weeks. The last few days alone have seen the debut of a number of wonderful games, so we thought we'd take the time to... | Read more »
Recruit more scallywags and discover new...
Get ready to show off your sea legs all over again in Oceans & Empires’ new grand update, which aims to make the act of rising to the role of seven seas ruler even more fresh and appealing, thanks to a richness of new content on both iOS and... | Read more »

Price Scanner via MacPrices.net

27-inch Apple iMacs on sale for up to $200 of...
B&H Photo has 27″ Apple iMacs on sale for up to $200 off MSRP, each including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2099.99 $200 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
Amazon has 2015 15″ 2.2GHz Retina MacBook Pros (MJLQ2LL/A) available for $1849.99 including free shipping. Apple charges $1999 for this model, so Amazon’s price is represents a $150 savings. Read more
Apple refurbished iPad Air 2s available start...
Apple has Certified Refurbished iPad Air 2 WiFis available for starting at $319 including free shipping. A standard Apple one-year warranty is included: - 16GB iPad Air 2 WiFi: $319 $60 off original... Read more
Apple refurbished iPad Pros available for up...
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 restocks refurbished 2015 and 2016 13-i...
Apple has Certified Refurbished 2015 and 2016 13″ MacBook Airs available starting at $759. An Apple one-year warranty is included with each MacBook, and shipping is free: - 2016 13″ 1.6GHz/8GB/128GB... Read more
13-inch 2.5GHz MacBook Pro (Apple refurbished...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros (MD101LL/A) available for $829, or $270 off original MSRP. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook... Read more
QuickerTek Announces 5TB Apple AC AirPort Tim...
QuickerTek Inc. has announced their new 5TB hard drive upgrade for Apple’s AC AirPort Time Capsule. By customer request, this upgrade also features six external antennas and offers the highest... Read more
Apple Certified Refurbished iMacs available f...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
Apple offering Certified Refurbished Series 1...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
1.4GHz Mac mini on sale for $449, save $50
B&H Photo has the 1.4GHz Mac mini on sale for $50 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP Read more

Jobs Board

*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
Manager *Apple* Systems Administration - Pu...
Req ID 3315BR Position Title Manager, Apple Systems Administration Job Description The Manager of Apple Systems Administration oversees the administration and 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
Manager *Apple* Systems Administration - Pu...
Req ID 3315BR Position Title Manager, Apple Systems Administration Job Description The Manager of Apple Systems Administration oversees the administration and Read more
*Apple* Technician - nfrastructure (United S...
Let’s Work Together Apple Technician This position is based in Portland, ME Life at nfrastructure At nfrastructure, we understand that our success results from our Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.