The GenProcess Object: 1 Starting and Stopping

For information about the steps involved in stopping, starting, or restoring an application (and to get context information about the messages described below), see the GEOS Programming chapter.

Many of the following messages need AppAttachFlags to tell them how the process is attaching:

typedef WordFlags AppAttachFlags;
#define AAF_RESTORING_FROM_STATE						0x8000
#define AAF_STATE_FILE_PASSED						0x4000
#define AAF_DATA_FILE_PASSED						0x2000
#define AAF_RESTORING_FROM_QUIT						0x1000

AAF_RESTORING_FROM_STATE indicates that the application is coming up from a previous state, either by re-launching using a state file, or re-entering application mode from engine mode in the same session. The UI trees will be in whatever state they were left in, which may be different than the statically declared UI tree, depending on what occurred in the application when the state file was written out (for example, a dialog box may have been on-screen). If this flag is false , the application is starting up fresh. If this flag is true , the UI does not call MSG_META_LOAD_OPTIONS and ignores any "ON_STARTUP" hints or attributes.
AAF_STATE_FILE_PASSED indicates that the application is restoring from the state file passed in an AppLaunchBlock , presumably passed as an argument in the message also. If this flag is set, AAF_RESTORING_FROM_STATE will also be set.
AAF_DATA_FILE_PASSED indicates that the passed AppLaunchBlock contains the name of a data file that should be opened.
AAF_RESTORING_FROM_QUIT indicates that the application was in the process of quitting, reached engine mode, and is now being started back up into application mode. If set, will also be set, and we will be brought up in whatever state we originally entered engine mode.

MSG_GEN_PROCESS_RESTORE_FROM_STATE

void 	MSG_GEN_PROCESS_RESTORE_FROM_STATE(
        AppAttachFlags 		attachFlags,
        MemHandle 		launchBlock,
        MemHandle 		extraState);

This message is sent by the User Interface when an application is being loaded from a state file. This is sent to the process itself from MSG_META_ATTACH , whenever the application is being invoked as in MSG_GEN_PROCESS_RESTORE_FROM_STATE mode. Data passed is the same as that in MSG_META_ATTACH . The default handler fetches the application mode message, either MSG_GEN_PROCESS_OPEN_APPLICATION or MSG_GEN_PROCESS_OPEN_ENGINE , as saved in the application object, and sends that message to the process.

Note that the blocks passed need not be freed, as this is done by the caller upon return.

Source: Default GenProcessClass handler for MSG_META_ATTACH.

Destination: Self.

Interception: Intercepted generally only so that application can retrieve previously saved data out of the state block passed.

Parameters: attachFlags Flags with information about the state and data files.

launchBlock: Handle of AppLaunchBlock , or zero if none. This block contains the name of any document file passed into the application on invocation.
extraState: Handle of extra state block, or zero if none. This is the same block as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION or MSG_GEN_PROCESS_CLOSE_ENGINE , in some previous MSG_META_DETACH . Process objects often use this extra block to save global variables to state files.

Return: Nothing.

MSG_GEN_PROCESS_OPEN_APPLICATION

void	MSG_GEN_PROCESS_OPEN_APPLICATION(
        AppAttachFlags		attachFlags,
        MemHandle		launchBlock,
        MemHandle 		extraState);

This message is sent by the User Interface when an application is being loaded from its resource blocks. Applications will often intercept this message to set up certain things before being put on-screen. This is the handler in which, for example, you would register for certain notifications such as the quick-transfer notification.

This is sent to the process itself from MSG_META_ATTACH , whenever the application is being restored to application mode (as opposed to engine mode), or whenever it is being invoked as in application mode. Data passed is the same as that in MSG_META_ATTACH . The default handler sets the GenApplication object GS_USABLE, and brings the UI up on screen.

This message may be intercepted to open up any data file passed, before the UI for the application is actually set GS_USABLE. Note that the blocks passed need not be freed, as this is done by the caller upon return.

If you intercept this message and need to send MSG_META_QUIT from within the handler, make sure to either send the quit after calling the superclass, or send the quit via MSG_META_FLUSH_INPUT_QUEUE. (If this is not done, the system will think that an IACP connection is open, aborting the quit.)

Source: GenProcessClass default handler for MSG_META_ATTACH only.

Destination: Same object.

Interception: Frequently intercepted by an application's own process class to find out when an application is first coming alive in the system. You must pass this message on to the superclass, or the application will never come up. Be aware that the entire UI tree for the application is the equivalent of not usable (~GS_USABLE) before the superclass is called, and is usable and up on screen visually after it is called. Thus, it is best to do non-UI related things, and changing of generic attributes and hints before calling the superclass. You must wait until after calling the superclass to perform any operations which require that objects be fully usable (e.g. bringing up a dialog box). Make sure that if you send MSG_META_QUIT from within your handler that you follow the guidelines mentioned above.

Parameters: attachFlags State information about the state and data files.

launchBlock: Handle of AppLaunchBlock , or zero if none. This block contains the name of any document file passed into the application on invocation.
extraState: Handle of extra state block, or zero if none. This is the same block as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION or MSG_GEN_PROCESS_CLOSE_ENGINE , in some previous MSG_META_DETACH .
Is freed by caller--subclasses should not free the extra state block.

Return: Nothing.

MSG_GEN_PROCESS_CLOSE_APPLICATION

MemHandle MSG_GEN_PROCESS_CLOSE_APPLICATION();

This message is sent by the User Interface whenever the application is being shut down (during a detach) and it had been launched in application (as opposed to engine) mode.

Source: GenProcessClass default handler for MSG_META_DETACH only

Destination: Self

Interception: Convenient place for code that needs to be executed before application exits, for non-engine mode cases. Superclass must be called.

Parameters: None.

Return: Handle of block to save (or NULL for none). Process objects often save global variables to a state file in an extra block. This is the handle of that block.

MSG_GEN_PROCESS_OPEN_ENGINE

void 	MSG_GEN_PROCESS_OPEN_ENGINE(
        AppAttachFlags 		attachFlags,
        MemHandle 		launchBlock);

This is sent to the process itself from MSG_META_ATTACH , whenever the application is being restored to engine mode, or whenever it is being invoked as in engine mode. Data passed is the same as that in MSG_META_ATTACH . There is no default handler.

This message may be intercepted to open up any data file passed, before any engine commands are delivered to the process. Note that the blocks passed need not be freed, as this is done by the caller upon return.

Source: GenProcessClass default handler for MSG_META_ATTACH only.

Destination: Self.

Interception: Generally unnecessary, though can be intercepted if notification of going into this mode is necessary.

Parameters: attachFlags State of state and data files.

launchBlock: Handle of AppLaunchBlock , or NULL if none. This block contains the name of any document file passed into the application on invocation.

Return: Nothing.

MSG_GEN_PROCESS_CLOSE_ENGINE

void 	MSG_GEN_PROCESS_CLOSE_ENGINE();

This message is sent by the User Interface whenever the application is being shut down (during a detach) and it had been launched in "engine" mode.

Source: GenProcessClass default handler for MSG_META_DETACH only.

Destination: Self.

Interception: Convenient place for code that needs to be executed before the application exits, for engine mode cases. Superclass must be called.

MSG_GEN_PROCESS_CLOSE_CUSTOM

MemHandle MSG_GEN_PROCESS_CLOSE_CUSTOM();

This message is sent by the User Interface whenever the application is being shut down (during a detach) and it had been launched in some custom mode (not application or engine) that GenProcessClass doesn't know about.

Source: Subclass of GenProcessClass .

Destination: Self.

Interception: Convenient place for code that needs to be executed before the application exits, for custom mode cases. Superclass must be called.

Parameters: None.

Return: Handle of block to save (or NULL for none).

MSG_GEN_PROCESS_ATTACH_TO_PASSED_STATE_FILE

MemHandle 	MSG_GEN_PROCESS_ATTACH_TO_STATE_FILE(
        AppAttachFlags		attachFlags,
        MemHandle		launchBlock);

This message is sent by the User Interface whenever the application is being attached to a state file. This message is sent when either restoring from state or detaching. May be subclassed to provide forced state behavior.

Source: GenProcessClass default handler for MSG_META_ATTACH .

Destination: Self.

Interception: May be intercepted to force use of a particular state file (by changing the name of the state file to use before calling superclass).

Parameters: attachFlags AppAttachMode (matches that in AppLaunchBlock ).

launchBlock: Block of structure AppLaunchBlock .

Return: Handle of extra block of state data (zero for none).

MSG_GEN_PROCESS_CREATE_NEW_STATE_FILE

word MSG_GEN_PROCESS_CREATE_NEW_STATE_FILE(
         MemHandle appInstanceReference);

This replaces MSG_GEN_PROCESS_ATTACHED_TO_PASSED_STATE_FILE if no state file had been specified in that message. This message's default handler will create a new state file and attach it normally. Can be subclassed to provide forced state file usage (e.g. use a different naming scheme).

Source: GenProcessClass default handler for MSG_META_DETACH, if not quitting.

Destination: Self.

Interception: May be intercepted to change name of state file to create.

Parameters: appInstanceReference
Block handle to block of structure AppInstanceReference .

Return: VM file handle (NULL if you want no state file).

MSG_GEN_PROCESS_DETACH_FROM_STATE_FILE

void 	MSG_GEN_PROCESS_DETACH_FROM_STATE_FILE(
        MemHandle 		extraState,
        word 		appStates);

This message is sent by the User Interface when the application is detaching or quitting (may or may not be attached to a state file) and the detach is nearly complete.

Source: GenProcessClass default handler for MSG_META_DETACH , if not quitting.

Destination: Self.

Interception: Not generally done. Default behavior is what you want.

Parameters: extraState Block handle of extra block to be saved (as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION , MSG_GEN_PROCESS_CLOSE_ENGINE or MSG_GEN_PROCESS_CLOSE_CUSTOM ). If the block is not transferred to the state file), it must be freed (if non-zero) by the handler for this message.

appStates: ApplicationStates record with information about the application state.

Return: Nothing.

MSG_GEN_PROCESS_INSTALL_TOKEN

void 	MSG_GEN_PROCESS_INSTALL_TOKEN();

This message is sent by the desktop to a process to get that process to install its token and moniker lists into the token database.

Source: Generally whatever geode launched this application in engine mode (e.g. GeoManager).

Destination: GenProcessClass object of any geode launched in engine mode.

Interception: May be intercepted to install additional tokens. Default behavior installs only application icon.

Parameters: None.

Return: Nothing.

MSG_GEN_PROCESS_GET_PARENT_FIELD

optr 	MSG_GEN_PROCESS_GET_PARENT_FIELD();

This message is sent by process-libraries (such as the Spool Object Library) to find out which field object is its parent. This message will return the field of the first client of the library.

Source: Unrestricted.

Destination: GenProcessClass object.

Interception: Not necessary, as default behavior implements utility.

Parameters: Nothing.

Return: Parent field.

MSG_GEN_PROCESS_SEND_TO_APP_GCN_LIST

void	MSG_GEN_PROCESS_SEND_TO_APP_GCN_LIST(@stack
        word		sendFlags,
        EventHandle 		event,
        MemHandle 		block,
        word		manufListType,
        ManufacturerID 		manufID);

This message sends the specified event to all the objects registered with the passed GCN list. This message should be subclassed by UI Controller objects.

The handler here merely sends the request on to GenApplication using MSG_META_GCN_LIST_SEND . Controllers should use this message, however, over direct communication with the application object, to ensure orderly updating of the list status event. One such failure case which is fixed is two target text objects, one run by the process thread in a view, the other a GenText run by the UI thread. If the GenText has the target and the user clicks quickly on view then GenText, the GenText may process both messages about the target being lost and gained before the process text object receives its gained and lost pair. If both objects sent MSG_META_GCN_LIST_SEND directly to the GenApplication object, the GenText's status would be wiped out by the subsequent reporting by the process text object. This problem is avoided by having both process and UI objects call here to pass status update info. This works because target changes start out ordered in the UI thread, and that order is passed on to the process thread in either of the two cases.

Source: Any object wishing to update an application GCN list. Don't use queue-order altering message flags such as MF_PLACE_IN_FRONT when sending this message. As a convention must be established for the flag MF_FORCE_QUEUE in order to ensure orderly results, the convention in use is this: Don't pass it.
A typical call should use only the MF_STACK, MF_FIXUP_DS, and/or MF_FIXUP_ES flags, if needed.

Destination: GenProcessClass (application process) only.

Interception: Should not generally be intercepted, as GenProcessClass provides correct behavior. If intercepted and not sent onto superclass, event passed must be destroyed and data block reference count decremented, to avoid leaving obsolete data on the heap.

Parameters: sendFlags Flags to pass on to GCNListSend() .

event: Classed event to pass on to the list.
block: Handle of extra data block, if used (otherwise NULL). Blocks of this type must have a reference count, which may be initialized with MemInitRefCount() and be incremented for any new usage with MemIncRefCount() . Methods in which they are passed are considered such a new usage, and must have MetaClass handlers which call MemDerefCount() . Current messages supported are MSG_META_NOTIFY_WITH_DATA_BLOCK and MSG_NOTIFY_FILE_CHANGE .
manufListType: This may be a GCNStandardListType or any other word which acts as a GCN list ID.
manufID: Manufacturer ID, which helps identify the GCN list.

GEOS SDK TechDocs |

The GenProcess Object | Next:

2 Undo Mechanism