Application Main Routine

A sample application main routine is illustrated in Figure "Sample Application Main Routine (Part 1) - Registration" and Figure "Sample Application Main Routine (Part 2) - Window Creation". The functions performed by the main routine are as follows:

  • Register the application to Presentation Manager, and obtain an anchor block handle (that is, an application handle), using the WinInitialize() function.

  • Create a message queue, into which Presentation Manager will place all messages intended for the application, using the WinCreateMsgQueue() function and passing both the anchor block handle and the required queue size to Presentation Manager, which returns a message queue handle to the application. Note that if the queue size specified is zero (as shown in the example above) then the default queue size of 10 messages is used.

  • Register one or more window classes, for the windows that will be created by the application, and associate a window procedure with each window class, using using the WinRegisterClass() function. Parameters passed to this function include the name of the window class and the name of the window procedure to be associated with the class. Presentation Manager returns a Boolean value indicating success or failure. Note the 4 bytes (32 bits) requested for window words, which may be used by the window procedure to store the address of its instance data block.

  • Create a main display window for the application, using two consecutive WinCreateWindow() calls (as shown in Figure "Sample Application Main Routine (Part 2) - Window Creation") or a single WinCreateStdWindow() call. Note the separate handles used for the frame and client windows. The values specified for fcdata.flCreateFlags control the appearance of the window, the controls it contains and its position on the screen.

  • Optionally, create an entry for the application in the Workplace Shell Window List, using the WinAddSwitchEntry() function. Note that this step is omitted from Figure "Sample Application Main Routine (Part 2) - Window Creation" for reasons of clarity, and is shown separately in Figure "WinAddSwitchEntry() Function".

    Note that under OS/2 Version 2.0, the WinCreateSwitchEntry() function is provided in addition to the WinAddSwitchEntry() function. These two functions accept identical parameters and carry out identical tasks; the WinCreateSwitchEntry() function is intended to provide consistent function naming conventions. The WinAddSwitchEntry() function is retained under OS/2 Version 2.0 for compatability with existing applications, but use of the WinCreateSwitchEntry() function is recommended.

  • Establish a message processing loop, whereby the application requests Presentation Manager to supply messages from the system queue and subsequently invokes Presentation Manager to dispatch them to the appropriate window procedure. This loop uses nested WinGetMsg() and WinDispatchMsg() calls.

  • Upon receivng the special message class WM_QUIT, which will cause WinGetMsg() to return false and hence terminate the while loop, remove any remaining windows using the WinDestroyWindow() function, remove the application's entry from the Window List using the WinRemoveSwitchEntry() function, destroy the message queue and deregister the application before terminating. These latter functions are achieved using the WinDestroyMsgQueue() and WinTerminate() calls.

    The structure of the main routine is similar for both the application (that is, the application's primary thread) and any secondary threads created by the application. See Multitasking Considerations for further discussion on secondary threads.

    In Figure "Sample Application Main Routine (Part 1) - Registration", note the use of the EXPENTRY keyword in the function prototype to specify the system linkage convention for the window procedure wpMain. This is required whenever declaring a window procedure or dialog procedure, since such procedures are normally invoked by Presentation Manager on the application's behalf, rather than directly by the application.

    If the application is to appear in and be selectable from the Workplace Shell Window List, the main routine must issue a WinAddSwitchEntry() function call, after creating the application's main window and before entering the message processing loop. [Note that under OS/2 Version 2.0, use of the WinCreateSwitchEntry() function is recommended, for reasons of consistency in function names. ] This function call is shown in Figure "WinAddSwitchEntry() Function".

    Note that the application may set the swTitle field of the SwitchData structure to NULL. Presentation Manager will then determine the title under which the application was started from the Presentation Manager shell, and use this title for the switch entry.

    The WinAddSwitchEntry() function returns a switch entry handle, which may be stored by the application and used during termination to remove the switch entry from the Workplace Shell Window List using the WinRemoveSwitchEntry() function.

    The switch entry may be accessed by a window procedure at any time during application execution. The switch entry handle is obtained using the WinQuerySwitchHandle() function, and the SwitchData control structure may then be obtained using the WinQuerySwitchEntry() function, and altered using the WinChangeSwitchEntry() function. This capability may be used to allow a window procedure to obtain the handle of the application's main window, in order to post or send messages to that window. This is discussed in Identifying the Destination Window.

    [Back: Object-Oriented Programming Practices]
    [Next: Using Windows]