Applications and Geodes: 1.2 Geodes: Launching an Application

1.1 Geode Components and Structures | Next:

GeodeLoad(), UserLoadApplication(), MSG_GEN_PROCESS_OPEN_APPLICATION

An application is a geode with its GA_APPLICATION attribute set. This type of geode may be launched by the user through GeoManager or some other means provided by the system or another application. For the most part, the system will invoke and carry out the launch; your responsibilities are limited.

An application may be loaded in essentially two ways: It may be launched, or it may be reloaded from a state file. In both cases, the kernel will load the proper resources and build out the UI properly according to the application.

Most of the procedure of launching is handled within GenProcessClass , a subclass of ProcessClass . An application should define its own subclass of GenProcessClass for its Process objects (event-driven threads not acting as Process objects should be subclassed from ProcessClass , not GenProcessClass ). The launch procedure may be invoked by any thread and by any geode in either of the following ways:

GeodeLoad() This loads a geode from a given file and begins executing it based on the geode's type. GeodeLoad() takes the name of the geode's file as well as a priority to set for the new geode's process thread, if it has one. GeodeLoad() first creates the process thread of the application, then sends this thread a message. The process thread (a subclass of GenProcessClass ) then creates a UI thread for the application.
UserLoadApplication() Used by most application launchers, this routine loads an application. (C programmers will generally use MSG_GEN_PROCESS_OPEN_APPLICATION instead.) This routine takes some additional parameters and can load a geode either in engine mode or from a state file as well as in the normal open mode (see below). The base functionality of opening and loading the geode is implemented in this routine by a call to GeodeLoad() . Note, however, that this routine may only open application geodes--geodes with the GA_APPLICATION attribute set.

Geodes may be launched in three modes:

Application mode launches the geode, loads all its active resources, builds its UI gadgetry, and sets it usable. The geode must be an application--that is, it must have its GA_APPLICATION attribute set.
Engine mode launches the geode but leaves its UI objects unusable (it never brings them on-screen). Engine mode is useful if you need to launch an application to grab information from it. GeoManager uses engine mode to launch an application, extract its icon, and put the icon in the token database. For efficiency, the application is never set usable, so its UI is never built.
Restore mode launches the geode from a saved state file, loading in resources and merging them with the default resources. This mode is invoked automatically by the UI if it is restoring the system or the geode from saved state. This mode is handled automatically by GenProcessClass (your Process object).

It is possible, however, for one application to launch another in a custom mode. If this is done, the application being launched is responsible for implementing the special mode.

When the launch process has been initiated with the above routines, a thread is created for the application and its Process object is loaded immediately. Also loaded is the application's GenApplication object. The Application and Process objects interact with the User Interface to load the objects on the application's active list and set them all usable, bringing them up on-screen.

Near the end of this procedure, just before the GenApplication is set usable, the Process object will receive a message based on the mode of launch. If the application must set up any special notification (such as for the quick-transfer mechanism) or must restore special state file data, it should intercept this message. Typically the message received will be MSG_GEN_PROCESS_OPEN_APPLICATION --two others are received (when restoring from state and when opening in engine mode), but they should not be intercepted.

GEOS SDK TechDocs |

1.1 Geode Components and Structures | Next:

1.3 Shutting Down an Application