GEOS SDK TechDocs
|
| 
3 Using Multiple Displays
| 
3.2 GenDisplayControl
If an application uses GenDisplay objects, it must have a GenDisplayGroup object. This object makes sure there is space in the GenPrimary for the displays.
The GenDisplayGroup must be either a child of the GenPrimary (in which case the specific UI will decide where to put the display area) or a child of a
GenInteraction
which is a child of the GenPrimary (if the application wants the display area in a specific part of the GenPrimary). The GenDisplayGroup should be run by the UI thread.
GenDisplayGroupClass
has no instance data which may be set or examined by the application. However,
GenDisplayGroupClass
is a subclass of
GenClass
, and inherits all of its instance data. When you declare a GenDisplayGroup, you may specify its
GenClass
instance data normally; you may also include any of the hints described in the following sections.
HINT_DISPLAY_GROUP_SEPARATE_MENUS, HINT_DISPLAY_GROUP_ARRANGE_TILED, HINT_DISPLAY_GROUP_FULL_SIZED_ON_STARTUP, HINT_DISPLAY_GROUP_OVERLAPPING_ON_STARTUP, HINT_DISPLAY_GROUP_FULL_SIZED_IF_TRANSPARENT_DOC_CTRL_MODE, HINT_DISPLAY_GROUP_TILE_HORIZONTALLY, HINT_DISPLAY_GROUP_TILE_VERTICALLY, HINT_DISPLAY_GROUP_SIZE_INDEPENDENTLY_OF_DISPLAYS
GenDisplayGroupClass is a subclass of GenClass. Other than vardata, this class adds no other instance data. There are several hints defined for
GenDisplayGroupClass
. Most of these hints specify how displays should be arranged on startup.
Code Display 4-3 GenDisplayGroup Instance Data
/* GenDisplayGroupClass adds no instance fields. It does modify the default
* GI_attrs settings, however. */
@default GI_attrs = @default | GA_TARGETABLE;
/* This hint allows each GenDisplay to contain its own menu bar. */
@vardata void HINT_DISPLAY_GROUP_SEPARATE_MENUS;
/* These hints specify how a GenDisplayGroup will arrange its GenDisplays. */
@vardata void HINT_DISPLAY_GROUP_ARRANGE_TILED;
@vardata void HINT_DISPLAY_GROUP_FULL_SIZED_ON_STARTUP;
@vardata void HINT_DISPLAY_GROUP_OVERLAPPING_ON_STARTUP;
@vardata void HINT_DISPLAY_GROUP_FULL_SIZED_IF_TRANSPARENT_DOC_CTRL_MODE;
@vardata void HINT_DISPLAY_GROUP_TILE_HORIZONTALLY;
@vardata void HINT_DISPLAY_GROUP_TILE_VERTICALLY;
@vardata void HINT_DISPLAY_GROUP_SIZE_INDEPENDENTLY_OF_DISPLAYS;
/* These attributes affect the availability of overlapping and
* full-sized states. */
@vardata void ATTR_GEN_DISPLAY_GROUP_NO_FULL_SIZED;
@vardata void ATTR_GEN_DISPLAY_GROUP_NO_OVERLAPPING;
@vardata void ATTR_GEN_DISPLAY_OVERLAPPING_STATE;
In some specific UIs (such as OSF/Motif), menus which are children of a GenDisplay object may appear in two ways: they may be drawn on the Primary's menu bar (the default in OSF/Motif), or they may appear in a menu bar on the display itself. HINT_DISPLAY_GROUP_SEPARATE_MENUS indicates that each display should be given its own menu bar (if the specific UI permits this).
There are several hints which specify how the displays should be configured when the GenDisplayGroup is built.
HINT_DISPLAY_GROUP_FULL_SIZED_ON_STARTUP indicates that the GenDisplayGroup should be in full-size mode on startup; that is, all of its children should be maximized.
HINT_DISPLAY_GROUP_OVERLAPPING_ON_STARTUP indicates that the GenDisplayGroup should be in overlapping mode on startup; that is, its children should be non-maximized.
HINT_DISPLAY_GROUP_FULL_SIZED_IF_TRANSPARENT_DOC_CTRL_MODE
forces a GenDisplayGroup to start full-sized if the application is in "transparent document control" mode, which is set by the user level of the application. This hint overrides
HINT_DISPLAY_GROUP_OVERLAPPING_ON_STARTUP
, if present.
HINT_DISPLAY_GROUP_ARRANGE_TILED indicates that the GenDisplayGroup should be in overlapping mode on startup, and further that the displays should be tiled; that is, they should be non-maximized and arranged in a non-overlapping way to fill the display area.
You can specify a preference for how the displays should be tiled by setting HINT_DISPLAY_GROUP_TILE_HORIZONTALLY or HINT_DISPLAY_GROUP_TILE_VERTICALLY . HINT_DISPLAY_GROUP_TILE_HORIZONTALLY indicates that you want tiled displays to be arranged horizontally, with each display tall enough to fill the display area. Similarly, HINT_DISPLAY_GROUP_TILE_VERTICALLY indicates that you want tiled displays to be arranged vertically, with each display wide enough to fill the display area. If both hints are set, the result varies depending on the specific UI.
HINT_DISPLAY_GROUP_SIZE_INDEPENDENTLY_OF_DISPLAYS
sizes a GenDisplayGroup by what its parent wants rather than what any of its children GenDisplays want. This may improve geometry performance in a complex GenPrimary/GenDisplay combination.
MSG_GEN_DISPLAY_GROUP_SET_OVERLAPPING, MSG_GEN_DISPLAY_GROUP_SET_FULL_SIZED, MSG_GEN_DISPLAY_GROUP_GET_FULL_SIZED, MSG_GEN_DISPLAY_GROUP_TILE_DISPLAYS, ATTR_GEN_DISPLAY_GROUP_NO_FULL_SIZED, ATTR_GEN_DISPLAY_GROUP_NO_OVERLAPPING, ATTR_GEN_DISPLAY_GROUP_OVERLAPPING_STATE
The GenDisplayGroup can be in "full-sized" or "overlapping" mode. If the GenDisplayGroup is in "full-size" mode, all of its children are maximized (except any displays which are set "non-maximizable"). If it is not in full-sized mode, it is said to be in "overlapping" mode; that is, none of its children are maximized. When a user maximizes any display which belongs to a GenDisplayGroup, the GenDisplayGroup automatically goes into "full-size" mode and maximizes all of its children.
If you include ATTR_GEN_DISPLAY_GROUP_NO_FULL_SIZED, the GenDisplayControl will not be able to go into full-size mode; it will always be in overlapping mode. Similarly, if set ATTR_GEN_DISPLAY_GROUP_NO_OVERLAPPING , the GenDisplayControl will not be able to go into overlapping mode; it will always be in full-sized mode, and all displays will always be maximized. Naturally, you may not include both of these attributes at once; if you do, results are undefined.
Messages are provided which switch the GenDisplayGroup into one or another of these modes. You might not need to use any of these messages. If you use a GenDisplayControl object, the user will be able to switch from overlapping to full-size and also to tile the displays by using that object. However, you can also send the following messages directly.
You can set a GenDisplayGroup to full-sized mode by sending it the message MSG_GEN_DISPLAY_GROUP_SET_FULL_SIZED. This message causes the GenDisplayGroup to maximize every one of its children. Children which cannot be maximized will be unaffected. The window layering and focus/target settings are not changed.
You can set a GenDisplayGroup to overlapping mode by sending it the message MSG_GEN_DISPLAY_GROUP_SET_OVERLAPPING. This message causes a GenDisplayGroup object to de-maximize all of its children. Children which are not restorable will be unaffected. The window layering and focus/target settings are not changed.
You can find out whether a GenDisplayGroup object is in full-sized mode by sending it
MSG_GEN_DISPLAY_GROUP_GET_FULL_SIZED
. If the GenDisplayGroup is in full-sized mode, this message will return
true
.
You can also put a GenDisplayGroup into "tiled" mode. This is a special case of overlapping mode. When a GenDisplayGroup is put in tiled mode, it first puts itself in overlapping mode. It then attempts to arrange and resize its display children so they fill the display area without overlapping. To put a GenDisplayGroup into tiled mode, send it the message
MSG_GEN_DISPLAY_GROUP_TILE_DISPLAYS
.
The GenDisplayGroup keeps track of its overlapping state across shutdowns. It does this by setting ATTR_GEN_DISPLAY_GROUP_OVERLAPPING_STATE. Applications may not set or change this attribute directly.
void MSG_GEN_DISPLAY_GROUP_SET_FULL_SIZED();
This message instructs a GenDisplayGroup to put itself in "full-sized" mode; that is, all of its maximizable children will be maximized. This message is ignored if the GenDisplayGroup has the vardata attribute ATTR_GEN_DISPLAY_GROUP_NO_FULL_SIZED.
Source: Unrestricted.
Destination: GenDisplayGroup.
Interception: Not generally intercepted.
void MSG_GEN_DISPLAY_GROUP_SET_OVERLAPPING();
This message instructs a GenDisplayGroup to put itself in "overlapping" mode. This message is ignored if the GenDisplayGroup has the vardata attribute ATTR_GEN_DISPLAY_GROUP_NO_OVERLAPPING.
Source: Unrestricted.
Destination: GenDisplayGroup.
Interception: Not generally intercepted.
Boolean MSG_GEN_DISPLAY_GROUP_GET_FULL_SIZED();
This message finds out whether a GenDisplayGroup is in "full-sized" mode.
Source: Unrestricted.
Destination: GenDisplayGroup.
Return: Returns true (i.e. non-zero) if the GenDisplayGroup is in full-sized mode; otherwise, it returns false (i.e. zero).
Interception: Not generally intercepted.
void MSG_GEN_DISPLAY_GROUP_TILE_DISPLAYS;
This message instructs a GenDisplayGroup to put itself in "tiled" mode. That is, it should first put itself in "overlapping" mode; it should then arrange and resize the displays so they fill the display area without overlapping. The message is ignored if the GenDisplayGroup has the vardata attribute ATTR_GEN_DISPLAY_GROUP_NO_OVERLAPPING.
Source: Unrestricted.
Destination: GenDisplayGroup.
Interception: Not generally intercepted.
MSG_GEN_DISPLAY_GROUP_SELECT_DISPLAY
Ordinarily, the user switches from one display to another in one of two ways. The user may use the specific UI's way of switching displays (e.g. clicking on the display); or he may use the GenDisplayControl (described below) to switch displays. The application can also force the Display Group to bring a certain display to the top by sending it
MSG_GEN_DISPLAY_GROUP_SELECT_DISPLAY
. However, this is not usually done; applications should generally let the user switch displays with the GenDisplayControl.
void MSG_GEN_DISPLAY_GROUP_SELECT_DISPLAY(
word displayNum);
This message instructs a display group to select a certain display, bringing it to the top and making it the focus. Applications should not ordinarily need to send this.
Source: Usually GenDisplayControl or its associated objects; however, any object can send this.
Destination: GenDisplayGroup.
Parameters: displayNum The display to select. This is an integer specifying the position of the desired display among the GenDisplayGroup's children; that is, its first child is number zero, its next child is number one, and so on.
Interception: This message is not ordinarily intercepted.
Tips: You can find a display's position number by sending
MSG_GEN_FIND_CHILD
to the GenDisplayGroup, passing the optr of the desired display. See the GenClass chapter.
GEOS SDK TechDocs
|
| 3 Using Multiple Displays
| 3.2 GenDisplayControl