Important: The information in this document is obsolete and should not be used for new development.
Launching Other Applications
You can launch other applications by calling the high-levelLaunchApplication
function. This function lets your application control various options associated with launching an application. For example, you can
Earlier versions of system software used a shorter parameter block as a parameter to the
- allow the application to be launched in a partition smaller than the preferred size but greater than the minimum size, or allow it to be launched only in a partition of the preferred size
- launch an application without terminating your own application, bring the launched application to the front, and get information about the launched application
- request that your application be notified if any application that it has launched terminates
_Launch
trap macro. The_Launch
trap macro still supports the use of this parameter block. Applications using theLaunchApplication
function should use the new launch parameter block (of typeLaunchParamBlockRec
). Use theGestalt
function and specify the selectorgestaltOSAttr
to determine which launch features are available.Most applications don't need to launch other applications. However, if your application includes a desk accessory or another application, you might use either the high-level
LaunchApplication
function to launch an application or theLaunchDeskAccessory
function to launch a desk accessory. For example, if you have implemented a spelling checker as a separate application, you might use theLaunchApplication
function to open the spelling checker when the user chooses Check Spelling from one of your application's menus.You specify a launch parameter block as a parameter to the
LaunchApplication
function. In this launch parameter block, you can specify the filename of the application to launch, specify whether to allow launching only in a partition of the preferred size or to allow launching in a smaller partition, and set various other options--for example, whether your application should continue or terminate after it launches the specified application.The
LaunchApplication
function launches the application from the specified file and returns the process serial number, preferred partition size, and minimum partition size if the application is successfully launched.Note that if you launch another application without terminating your application, the launched application does not actually begin executing until you make a subsequent call to
WaitNextEvent
orEventAvail
.The launch parameter block is defined by the
LaunchParamBlockRec
data type.
TYPE LaunchParamBlockRec = RECORD reserved1: LongInt; {reserved} reserved2: Integer; {reserved} launchBlockID: Integer; {extended block} launchEPBLength: LongInt; {length of block} launchFileFlags: Integer; {app's Finder flags} launchControlFlags: LaunchFlags; {launch options} launchAppSpec: FSSpecPtr; {location of app's file} launchProcessSN: ProcessSerialNumber; {returned psn} launchPreferredSize: LongInt; {returned pref size} launchMinimumSize: LongInt; {returned min size} launchAvailableSize: LongInt; {returned avail size} launchAppParameters: AppParametersPtr; {high-level event} END;In thelaunchBlockID
field, specify the constantextendedBlock
to identify the parameter block and to indicate that you are using the fields following it in the launch parameter block.
CONST extendedBlock = $4C43; {extended block}In thelaunchEPBLength
field, specify the constantextendedBlockLen
to indicate the length of the remaining fields in the launch parameter block (that is, the length of the fields following thelaunchEPBLength
field). For compatibility, you should always specify the length value in this field.
CONST extendedBlockLen = sizeof(LaunchParamBlockRec) - 12;ThelaunchFileFlags
field contains the Finder flags for the application file. (See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for a description of the Finder flags.) TheLaunchApplication
function sets this field for you if you set the bit defined by thelaunchNoFileFlags
constant in thelaunchControlFlags
field. Otherwise, you must get the Finder flags from the application file and set this field yourself (by using the File Manager routineFSpGetFInfo
, for example).In the
launchControlFlags
field, you specify various options that control how the specified application is launched. See the section "Launch Options" on page 2-15 for information on the launch control flags.You specify the application to launch in the
launchAppSpec
field of the launch parameter block. In this field, you specify a pointer to a file system specification record (FSSpec
). See the chapter "File Manager" in Inside Macintosh: Files for a complete description of the file system specification record.The
LaunchApplication
function sets the initial default directory of the application to the parent directory of the application file.If it successfully launches the application,
LaunchApplication
returns, in thelaunchProcessSN
field, a process serial number. You can use this number in Process Manager routines to refer to this application.The
LaunchApplication
function returns thelaunchPreferredSize
andlaunchMinimumSize
fields of the launch parameter block. The values of these fields are based on their corresponding values in the'SIZE'
resource. These values may be greater than those specified in the application's'SIZE'
resource because the returned sizes include any adjustments to the size of the application's stack. See the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information on how the size of the application stack is adjusted. Values are always returned in these fields whether or not the launch was successful. These values are 0 if an error occurred--for example, if the application file could not be found.The
LaunchApplication
function returns a value in thelaunchAvailableSize
field only when thememFullErr
result code is returned. This value indicates the largest partition size currently available for allocation.The
launchAppParameters
field specifies the first high-level event sent to an application. If you set this field toNIL
, theLaunchApplication
function automatically creates and sends an Open Application event to the launched application. (See the chapter "Apple Event Manager" in Inside Macintosh: Interapplication Communication for a description of this event.) To send a particular high-level event to the launched application, you can specify a pointer to an application parameters record. The application parameters record is defined by the data typeAppParameters
.
TYPE AppParameters = RECORD theMsgEvent: EventRecord; {event (high-level)} eventRefCon: LongInt; {reference constant} messageLength: LongInt; {length of buffer} messageBuffer: ARRAY [0..0] OF SignedByte; END;You specify the high-level event in the fieldstheMsgEvent
,eventRefCon
,messageLength
, andmessageBuffer
.Listing 2-2 demonstrates how you can use the
LaunchApplication
function.Listing 2-2 Launching an application
PROCEDURE LaunchAnApplication (mySFReply: StandardFileReply); VAR myLaunchParams: LaunchParamBlockRec; launchedProcessSN: ProcessSerialNumber; launchErr: OSErr; prefSize: LongInt; minSize: LongInt; availSize: LongInt; BEGIN WITH myLaunchParams DO BEGIN launchBlockID := extendedBlock; launchEPBLength := extendedBlockLen; launchFileFlags := 0; launchControlFlags := launchContinue + launchNoFileFlags; launchAppSpec := @mySFReply.sfFile; launchAppParameters := NIL; END; launchErr := LaunchApplication(@myLaunchParams); prefsize := myLaunchParams.launchPreferredSize; minsize := myLaunchParams.launchMinimumSize; IF launchErr = noErr THEN launchedProcessSN := myLaunchParams.launchProcessSN ELSE IF launchErr = memFullErr THEN availSize := myLaunchParams.launchAvailableSize ELSE DoError(launchErr); END;Listing 2-2 indicates which application file to launch by using a file system specification record (perhaps returned by theStandardGetFile
routine) and specifying, in thelaunchAppSpec
field, a pointer to this record. ThelaunchControlFlags
field indicates thatLaunchApplication
should extract the Finder flags from the application file, launch the application in a partition of the preferred size, bring the launched application to the front, and not terminate the current process.By default,
LaunchApplication
brings the launched application to the front and sends the foreground application to the background. If you don't want to bring an application to the front when it is first launched, set thelaunchDontSwitch
flag in thelaunchControlFlags
field of the launch parameter block.In addition, if you want your application to continue to run after it launches another application, you must set the
launchContinue
flag in thelaunchControlFlags
field of the launch parameter block. For a complete description of the available launch control options, see "Launch Options" on page 2-15.If you want your application to be notified about the termination of an application it has launched, set the
acceptAppDiedEvents
flag in your'SIZE'
resource. If you set this flag and an application launched by your application terminates, your application receives an Application Died Apple event ('aevt'
'obit'
). See "Terminating an Application" on page 2-11 for more information on the Application Died event.