Events order on application startup

From REALbasicWiki

This article is a stub. You can help the REALbasicWiki community by expanding it.

   This article applies only to Mac  

Between the time the user chooses to start your application up and the time the application is ready for use, many things happen. Besides the system loading the code into memory, linking against libraries and so on, your application may be asked to behave differently depending on how the user has invoked it. So there may be differences in the way the Application object events get called and such behavior is platform-dependent.

[edit] Mac OS X

[edit] At the system level

On Mac OS X, communication between the system and the application is done through a small number of AppleEvents whose class ID is the four-char code 'aevt'.

	Event class	Event ID
Open application	aevt	oapp
Open document(s)	aevt	odoc
Print document(s)	aevt	pdoc
Reopen application	aevt	rapp

• First, the application is launched by the system. In this step, the application should initialize, i.e. it should execute the minimum necessary actions to get ready for further interaction with the system. It should not present any window to the user yet.
• Then the first AppleEvent is sent. It can be one of:
  • 'aevt/oapp': This happens when the user has double-clicked on the application icon. If your application is document-based, normal behavior is to open a new empty document. Note that if the user then opens a document and the default document has not been modified, then your application should automatically close the default empty document without user interaction.
  • 'aevt/odoc': This event is sent as the first event when the user has double-clicked on one or more documents or dragged & dropped one or more documents onto the application icon. Your application should then process the file. In the case where more than one document are passed, you may choose to process them one by one or altogether, depending on your application features.
  • 'aevt/pdoc': When received as the first application event, your application should open the given documents, print them using default settings, close the documents and quits.

Note that another AppleEvent is used when the user reopens an application, either by double-clicking on its icon or by selecting it from the Dock: 'aevt/rapp'. As for 'aevt/oapp', and if your application is document-based, you should create a new empty document if no document is already opened.

[edit] How REALbasic copes with the system-level events

Because of its cross-platform nature, REALbasic must use a sensible way to raise approximately the same events for Mac OS X, Windows and Linux. As a consequence, only a part of the Mac OS X system-level events are used.

• Application.Open is always called first, no matter how your application is launched.
• Application.NewDocument is the REALbasic equivalent to 'aevt/oapp'. It simulates the fact that a document-based application is supposed to automatically create an empty document at startup. However, this event is not called on receiving 'aevt/rapp' AppleEvent (which is not processed at all by REALbasic).
• Application.OpenDocument is called in the same conditions as 'aevt/odoc' described above. However, this REALbasic event will be invoked for each document separately. If you need to know whether there is a single file or several files to open, you should process the AppleEvent right from Application.HandleAppleEvent.

The 'aevt/rapp' AppleEvent is not used by REALbasic.

The only way your project can properly handle all of the system-level events on Mac OS X is to intercept and process them by yourself from the Application.HandleAppleEvent event.