Window Objects: 2 Using the GenPrimary

| Up: GEOS SDK TechDocs | Up | Prev: 1 A First Look at GenDisplay | Next: 3 Using Multiple Displays 
MSG_GEN_PRIMARY_GET_LONG_TERM_MONIKER, MSG_GEN_PRIMARY_USE_LONG_TERM_MONIKER, MSG_GEN_PRIMARY_REPLACE_LONG_TERM_MONIKER, HINT_PRIMARY_FULL_SCREEN, HINT_PRIMARY_NO_FILE_MENU, HINT_PRIMARY_NO_EXPRESS_MENU, HINT_PRIMARY_OPEN_ICON_BOUNDS, HINT_PRIMARY_NO_HELP_BUTTON

Almost every application will have a single GenPrimary object. GEOS uses the GenPrimary to create and manage the primary window of an application. A few applications may have several GenPrimary objects; a very few will have no GenPrimary at all. (Applications with no GenPrimary generally do not have any user interface; they often are intended to work with other applications, communicating via streams.)

The structure of the GenPrimary object is almost the same as that of GenDisplay. The instance data definitions for GenPrimaryClass are shown in Instance data for GenPrimaryClass below.

Code Display 4-2 Instance data for GenPrimaryClass

/* There is only one instance field specifically defined for GenPrimaryClass. */
/* A GenPrimary object can have a long moniker, which is displayed at the top of
 * the window. The moniker is stored in a chunk in the object block containing the
 * GenPrimary; the attribute GPI_longTermMoniker contains the handle of this
 * chunk. The long-term moniker is described below.*/
    @instance ChunkHandle				GPI_longTermMoniker;
/* GenPrimaryClass also modifies the default GI_attrs settings. */
    @default GI_attrs = @default | GA_TARGETABLE;
/* HINT_PRIMARY_FULL_SCREEN indicates that the primary object should be sized to
 * fill a large portion of the screen. If this hint is not present, the Primary
 * will be just large enough to accommodate its children.*/
    @vardata void 			HINT_PRIMARY_FULL_SCREEN;
/* Ordinarily, every Primary window is created with a File menu. You can suppress
 * this by including HINT_PRIMARY_NO_FILE_MENU. */
    @vardata void 			HINT_PRIMARY_NO_FILE_MENU;
/* Also by default, any launched Primary window gets added to the Express Menu. If 
 * you wish to suppress this behavior, add HINT_PRIMARY_NO_EXPRESS_MENU. */
    @vardata void			HINT_PRIMARY_NO_EXPRESS_MENU;
/* If a primary object is minimizable, the location of the minimized primary is
 * stored in the vardata field HHINT_PRIMARY_OPEN_ICON_BOUNDS.
 */
    @vardata Rectangle			 HINT_PRIMARY_OPEN_ICON_BOUNDS
/* By default, all primary windows have a "help" button; when the user clicks on
 * it, the window's help text is brought up. If you don't want the primary to
 * provide help text, you can use the hint HINT_PRIMARY_NO_HELP_BUTTON.
 */
    @vardata void 		 HINT_PRIMARY_NO_HELP_BUTTON;

When a Primary window is created, it is usually sized to contain all of its components. However, you can suggest that it be sized to fill almost all the screen by setting the hint HINT_PRIMARY_FULL_SCREEN . This hint says that the Primary should be sized to fill a large portion of the screen, though not all of it. (For example, OSF/Motif sets the Primary to fill the whole screen except for a narrow space for icons at the bottom.) If this hint is not present, the Primary will be just large enough to accommodate its children.

A GenPrimary normally creates a File menu within its menu bar. To suppress creation of this file menu, add HINT_PRIMARY_NO_FILE_MENU . GenPrimarys, by default, are also added to the list of active applications within the system's express menu. Add HINT_PRIMARY_NO_EXPRESS_MENU if you wish to avoid adding the launched GenPrimary to the express menu.

When a Primary is minimized, it is displayed as an icon with a caption beneath it. The icon and caption will be taken from the Primary's moniker list (GI _visMoniker ). If the Primary lacks either a text moniker or a graphic moniker, the missing moniker will be read from the Application object's GI _visMoniker field. Most applications will not set GI _visMoniker in the Primary object, since it would usually mean duplicating the monikers already in the Application object. However, some applications will set this (e.g. because they have several Primary objects and want each one to have a different icon when minimized).

When the Primary is expanded from a minimized state, its minimized location is stored in the hint HINT_PRIMARY_OPEN_ICON_BOUNDS. The next time the Primary is minimized, it will be returned to that location.

GPI_longTermMoniker contains a secondary moniker for the Primary object. This moniker is displayed along with the Primary moniker, in a way which depends on the specific UI. (In OSF/Motif, the Primary's text monikers are shown in its title bar: first the text moniker from GI _visMoniker , then a dash, then the moniker from GPI_longTermMoniker .) If the GenPrimary has a GenDisplayGroup as a child, the GenDisplayGroup will automatically set this field to contain the moniker of the top-most GenDisplay. The application can override this by sending the Primary MSG_GEN_PRIMARY_USE_LONG_TERM_MONIKER, described below.

Most Primary objects will have help text; under most specific UIs, the Primary will have a "help" button to bring up this text. If you don't want to provide help text, you should set the hint HINT_PRIMARY_NO_HELP_BUTTON .

MSG_GEN_PRIMARY_GET_LONG_TERM_MONIKER
ChunkHandle 	MSG_GEN_PRIMARY_GET_LONG_TERM_MONIKER();

Use this message to find out the moniker of a GenPrimary object. The message returns the chunk handle of the moniker; the moniker is in the same block as the GenPrimary object.

Source: Unrestricted.

Destination: GenPrimary.

Return: Returns the chunk handle of the primary's long-term moniker. The chunk is in the same object block as the GenPrimary.

Interception: This message is not ordinarily intercepted.

MSG_GEN_PRIMARY_USE_LONG_TERM_MONIKER
void 	MSG_GEN_PRIMARY_USE_LONG_TERM_MONIKER(
        ChunkHandle		moniker);			/* must be in same object block as
					 * primary */

This message instructs a primary window to change its long-term moniker. The new long-term moniker must already be in a chunk in the same object block as the Primary. The chunk containing the obsolete long-term moniker will not be freed; you must do this manually.

Source: Unrestricted.

Destination: GenPrimary.

Parameters: moniker ChunkHandle of chunk in same object block as the GenPrimary. The chunk should contain the new long-term moniker.

Interception: This message is not ordinarily intercepted.

MSG_GEN_PRIMARY_REPLACE_LONG_TERM_MONIKER
void	MSG_GEN_PRIMARY_REPLACE_LONG_TERM_MONIKER(@stack
        VisUpdateMode 		updateMode,
        word 		height, 
        word 		width, 
        word 		length,
        VisMonikerDataType 		dataType,
        VisMonikerSourceType 		sourceType,
        dword 		source);

This message is used to replace a primary's long term moniker with a new one. This message's arguments are precisely like those to the message MSG_GEN_REPLACE_VIS_MONIKER . Note that a long term moniker is ordinarily a simple text string. For more information, see the GenClass chapter.

Source: Unrestricted.

Destination: GenPrimary.

Parameters: The parameters are the same as those for MSG_GEN_REPLACE_VIS_MONIKER .

Return: Returns the chunk handle of the new long-term moniker. The moniker will be allocated in the Primary's object block.

Interception: This message is not ordinarily intercepted.

| Up: GEOS SDK TechDocs | Up | Prev: 1 A First Look at GenDisplay | Next: 3 Using Multiple Displays