Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

The Size Resource
Every application executing in System 7, as well as every application executing under MultiFinder, should contain a size ('SIZE') resource. One of the principal functions
of the 'SIZE' resource is to inform the Operating System about the memory size requirements for the application so that the Operating System can set up an appropriately sized partition for the application. The 'SIZE' resource is also used to indicate certain scheduling options to the Operating System, such as whether the application can accept suspend and resume events. The 'SIZE' resource in System 7 contains additional information indicating whether the application is 32-bit clean, whether it supports stationery documents, whether it uses TextEdit's inline input services, whether the application wishes to receive notification of the termination of
any applications it has launched, and whether the application wishes to receive high- level events.
A 'SIZE' resource consists of a 16-bit flags field followed by two 32-bit size fields. The flags field specifies operating characteristics of the application, and the size fields indicate the minimum and preferred partition sizes for the application. The minimum partition size is the actual limit below which your application will not run. The preferred partition size is the memory size at which your application can run most effectively and which the Operating System attempts to secure upon launching the application. If that amount of memory is unavailable, the application is placed into the largest contiguous block available, provided that it is larger than the specified minimum size.

Note
If the amount of available memory is between the minimum and the preferred sizes, the Finder displays a dialog box asking if the user wants to run the application using the amount of memory available. If your application does not have a 'SIZE' resource, it is assigned a default partition size of 512 KB and the Process Manager uses a default value
of FALSE for all specifications normally defined by constants in the
flags field. u
When you define a 'SIZE' resource, you should give it a resource ID of -1. A user can modify the preferred size in the Finder's information window for your application. If the user does alter the preferred partition size, the Operating System creates a new 'SIZE' resource having resource ID 0. The Process Manager also creates a new 'SIZE' resource when the user modifies any of the other settings in the resource.
In system software version 7.1 the user can also modify the minimum size in the Finder's information window for your application. In version 7.1, if the user alters either the minimum or the preferred partition size, the Operating System creates two new 'SIZE' resources, one with resource ID 0 and one with resource ID 1.
At application launch time, the Process Manager looks for a 'SIZE' resource with ID 0 for the preferred partition size; if this resource is not found, it uses your original 'SIZE' resource with ID -1. In version 7.1, the Process Manager looks for a 'SIZE' resource with ID 0 for the preferred size and looks for a 'SIZE' resource with ID 1 for the minimum size; if these resources are not found, it uses your original 'SIZE' resource with ID -1.
Listing 2-19 shows the structure of the 'SIZE' resource in Rez format. See Listing 2-4 in "Creating a Size Resource," beginning on page 2-30 for a sample 'SIZE' resource for
an application.
Listing 2-19 A Rez template for a 'SIZE' resource
type 'SIZE' {
   boolean  reserved;                  /*reserved*/
   boolean  ignoreSuspendResumeEvents, /*ignores suspend-resume events*/
            acceptSuspendResumeEvents; /*accepts suspend-resume events*/
   boolean  reserved;                  /*reserved*/
   boolean  cannotBackground,          /*can't use background null events*/
            canBackground;             /*can use background null events*/
   boolean  needsActivateOnFGSwitch,   /*needs activate event following */
                                       /* major switch*/
            doesActivateOnFGSwitch;    /*activates own windows in */
                                       /* response to OS events*/
   boolean  backgroundAndForeground,   /*app has a user interface*/
            onlyBackground;            /*app has no user interface*/
   boolean  dontGetFrontClicks,        /*don't return mouse events */
                                       /* in front window on resume*/
            getFrontClicks;            /*do return mouse events */
                                       /* in front window on resume*/
   boolean  ignoreAppDiedEvents,       /*applications use this*/
            acceptAppDiedEvents;       /*app launchers use this*/
   boolean  not32BitCompatible,        /*works with 24-bit addr*/
            is32BitCompatible;         /*works with 24- or 32-bit addr*/
   boolean  notHighLevelEventAware,    /*can't use high-level events*/
            isHighLevelEventAware;     /*can use high-level events*/
   boolean  onlyLocalHLEvents,         /*only local high-level events*/
            localAndRemoteHLEvents;    /*also remote high-level events*/
   boolean  notStationeryAware,        /*can't use stationery documents*/
            isStationeryAware;         /*can use stationery documents*/
   boolean  dontUseTextEditServices,   /*can't use inline services*/
            useTextEditServices;       /*can use inline services*/
   boolean  reserved;                  /*reserved*/
   boolean  reserved;                  /*reserved*/
   boolean  reserved;                  /*reserved*/
                                       /*memory sizes are in bytes*/
   unsigned longint;                   /*preferred memory size*/
   unsigned longint;                   /*minimum memory size*/
};
The nonreserved bits in the flags field have the following meanings:

Flag descriptions
acceptSuspendResumeEvents
When set, indicates that your application can process suspend and resume events (which the Operating System sends to your application before sending it into the background or when bringing it into the foreground).
Note
If you set the acceptSuspendResumeEvents flag, you should also set the doesActivateOnFGSwitch flag. u
canBackground
When set, indicates that your application wants to receive null event processing time while in the background. If your application has nothing to do in the background, you should not set this flag.
doesActivateOnFGSwitch
When set, indicates that your application takes responsibility for activating and deactivating any windows in response to a suspend or resume event. If the acceptSuspendResumeEvents flag is set, if the doesActivateOnFGSwitch flag is not set, and if your application is suspended, then your application receives an activate event following the suspend event. However, if you set the doesActivateOnFGSwitch flag, then your application won't receive activate events associated with operating-system events, and you must take care of activation and deactivation when it receives the corresponding suspend or resume event. This means that if a window of your application is frontmost, you should treat
a suspend event as though a deactivate event were received as
well (assuming that both the doesActivateOnFGSwitch and acceptSuspendResumeEvents flags are set). For example, you should hide scroll bars, hide any caret, and unhighlight any selected text if your application moves to the background. If you do not set this flag, the Process Manager creates an offscreen window to force the activate and deactivate events to occur.
onlyBackground
When set, indicates that your application runs only in the background. Usually this is because it does not have a user interface
and cannot run in the foreground.
getFrontClicks
When set, indicates that your application is to receive the mouse-down and mouse-up events that are used to bring your application into the foreground when the user clicks in your application's frontmost window. Typically, the user simply wants to bring your application into the foreground, so it is usually not desirable to receive the mouse events (which would probably move the insertion point or start drawing immediately, depending on the application). The Finder is one application, however, that has the getFrontClicks flag set.

When the user clicks in the front window of your application and causes a foreground switch, your application receives a resume event. Your application should activate its front window in response to the resume event. In this case if your application's getFrontClicks flag is not set, your application does not receive the associated mouse event that caused the foreground switch. If your application's getFrontClicks flag is set, your application does receive the associated mouse event.

Your application always receives the associated mouse event when the user clicks in one of your application's windows other than the front window and causes a foreground switch.

When your application receives a mouse-down event in System 7, your application can examine bit 0 of the modifiers field of the event record to determine if the mouse-down event caused a foreground switch. This information can be especially useful if your application sets its getFrontClicks flag. For example, your application can examine bit 0 to determine whether to process the mouse-down event (probably depending on whether the clicked item was visible before the foreground switch).
acceptAppDiedEvents
When set, indicates that your application is to be notified whenever an application launched by your application terminates or crashes. If the Process Manager is available, your application receives this information as an Apple event, the Application Died event. See the chapter "Process Manager" chapter in Inside Macintosh: Processes for more information about launching applications and receiving Application Died events.
Note
Some early versions of MultiFinder do not send application-died events, and your application should not depend on receiving them if it is running in System 6. These events are provided primarily for use by debuggers. u
is32BitCompatible
When set, indicates that your application can be run with the 32-bit Memory Manager. You should not set this flag unless you have thoroughly tested your application on a 32-bit system (such as
a Macintosh IIci computer running System 7 in 32-bit mode or under A/UX).
isHighLevelEventAware
When set, indicates that your application can send and receive high-level events. If this flag is not set, the Event Manager does
not give your application high-level events when you call WaitNextEvent. There is no way to mask out specific types of high-level events; if this flag is set, your application receives all types of high-level events sent to your application.

Your application must support the four required Apple events if you set the isHighLevelEventAware flag. See Inside Macintosh: Interapplication Communication for information that describes how
to respond to the four required Apple events.
localAndRemoteHLEvents
When set, indicates that your application is to be visible to applications running on other computers on a network (in addition to applications running on the local computer). If this flag is not
set, your application does not receive high-level events across
a network.
isStationeryAware
When set, indicates that your application can recognize stationery documents. If this flag is not set and the user opens a stationery document, the Finder duplicates the document and prompts the user for a name for the duplicate document. For information about how your application can use stationery documents, see the chapter "Finder Interface" in this book.
useTextEditServicesWhen set, indicates that your application can use the inline text services provided by TextEdit. See Inside Macintosh: Text for information about the inline input capabilities of TextEdit.

The numbers you specify as your application's preferred and minimum memory sizes depend on the particular memory requirements of your application. Your application's memory requirements depend on the size of your application's static heap, dynamic heap, A5 world, and stack. (See "Introduction to Memory Management" in Inside Macintosh: Memory for complete details about these areas of your application's partition.)
The static heap size includes objects that are always present during the execution of the application--for example, code segments, Toolbox data structures for window records, and so on.
Dynamic heap requirements depend on how many objects are created on a per- document basis (which may vary in size proportionally with the document itself)
and the number of objects that are required for specific commands or functions.
The size of the A5 world depends on the amount of global data and the number of intersegment jumps the application contains.
Finally, the stack contains variables, return addresses, and temporary information. The application stack size varies among computers, so you should base your values for the stack size according to the stack size required on a Macintosh Plus (8 KB). The Process Manager automatically adjusts your requested amount of memory to compensate for the different stack sizes on different machines. For example, if you request 512 KB, more stack space (approximately 16 KB) will be allocated on machines with larger default stack sizes.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.