Window Objects: 3.3 Using Multiple Displays: Using GenDisplayClass Objects

| Up: GEOS SDK TechDocs | Up | Prev: 3.2 GenDisplayControl

All GenDisplay objects must be children of a GenDisplayGroup object. GenDisplay objects can be created in several ways: an application can declare them in its code; it can instantiate them at run-time and make them children of the GenDisplayGroup; or, if the application uses the Document Control objects, it can have the Document Control create a new display automatically whenever a document is opened. (For details about using a Document Control to create GenDisplay objects, see the Documents Objects chapter.)

Closing GenDisplays

MSG_GEN_DISPLAY_CLOSE

Most specific UIs provide a way for the user to close windows. For example, OSF/Motif lets a user close a window by double-clicking the control button. When the user uses the specific UI's close mechanism, the Display or Primary is sent MSG_GEN_DISPLAY_CLOSE.

GenDisplayClass does only one thing when it receives MSG_GEN_DISPLAY_CLOSE: it sends MSG_GEN_DOCUMENT_CLOSE to the document specified by GDI _document . The GenDisplayClass handler for MSG_GEN_DISPLAY_CLOSE does not, in fact, destroy the display. If the display is linked to a GenDocument, the GenDocument will respond to MSG_GEN_DOCUMENT_CLOSE by closing the application and removing the GenDisplay. Otherwise, you will have to remove the GenDisplay yourself by writing a handler for MSG_GEN_DISPLAY_CLOSE.

The GenPrimaryClass handler for MSG_GEN_DISPLAY_CLOSE closes the application. If you want to add to or replace this behavior, you may have your Primary subclass this message.

MSG_GEN_DISPLAY_CLOSE

void	MSG_GEN_DISPLAY_CLOSE();

This message is sent to a Display to close it. The system sends it when the user uses the specific UI's way of closing a window. The GenDisplayClass handler does nothing but send a MSG_GEN_DOCUMENT_CLOSE to the Document object specified in GDI _document . The GenPrimaryClass handler closes the application.

Source: Unrestricted.

Destination: GenDisplay.

Interception: If the Display is not associated with a GenDocument, you will need to subclass this message for it to have any effect at all. If the display is associated with a GenDocument object, you should probably subclass your Document object's MSG_GEN_DOCUMENT_CLOSE instead. Primary objects may subclass this message if they want to alter or replace the default behavior (of closing the application).

Menu Bar PopOuts

ATTR_GEN_DISPLAY_MENU_BAR_POPPED_OUT

Some objects contain the ability to "pop out" of their sub-group locations and become floating dialog boxes.The menu bar of a GenDisplay is one such GenInteraction. If the menu bar of a GenDisplay is currently in the "popped-out" state, it will contain the vardata entry ATTR_GEN_DISPLAY_MENU_BAR_POPPED_OUT.

Messages sent to GenDisplays

MSG_GEN_DISPLAY_UPDATE_FROM_DOCUMENT, MSG_GEN_DISPLAY_GET_DOCUMENT

Many of the messages which can be sent to GenDisplay objects have already been discussed above in A First Look at GenDisplay . However, there are a few messages which are ordinarily sent to Displays but not to Primaries. These messages are discussed here.

GenDisplay objects often work in close conjunction with the Document Control objects. It is common for every open document to have its own GenDisplay object as well as its own GenDocument. The two objects work in conjunction, sending messages back and forth to communicate. You can send or intercept these messages yourself to add functionality.

When the document object changes in certain significant ways, the Display has to be brought into accord with it. For example, if the name of the file changes, the GenDisplay's moniker will have to be changed to reflect this. Whenever a significant change takes place, the Document Control objects send a MSG_GEN_DISPLAY_UPDATE_FROM_DOCUMENT to the appropriate Display. The Display then requests all necessary information from the GenDocument and makes any necessary changes to its own instance data. You can force this updating by sending the message directly to the Display. You can also subclass this message if you want to add special updating behavior; however, you should be sure to pass this message to the superclass' handler.

You can find out which Document object is associated with a given Display by sending MSG_GEN_DISPLAY_GET_DOCUMENT to the Display. The message will return an optr to the corresponding Document object.

MSG_GEN_DISPLAY_UPDATE_FROM_DOCUMENT

void	MSG_GEN_DISPLAY_UPDATE_FROM_DOCUMENT();

This message instructs a GenDisplay to update its instance data from its associated GenDocument object (if any). This message is ordinarily sent by the Document Control objects.

Source: Unrestricted--ordinarily sent only by Document Control objects.

Destination: GenDisplay.

Interception: Normally not intercepted. If you subclass this message to add special updating behavior, be sure to end with an @callsuper.

MSG_GEN_DISPLAY_GET_DOCUMENT

optr	MSG_GEN_DISPLAY_GET_DOCUMENT();

This message returns the optr of the GenDocument associated with a given GenDisplay. This is equal to the value of the GenDisplay's GDI _document field.

Source: Unrestricted--ordinarily sent only by Document Control objects.

Destination: GenDisplay.

Interception: Normally not intercepted.

Traveling Objects

ATTR_GEN_DISPLAY_TRAVELLING_OBJECTS

If you use multiple GenDisplay objects, it is sometimes useful to set up a group of "traveling objects." Traveling objects are children of whichever display is active. When a different GenDisplay is brought to the top, all traveling objects will be set "not usable" and removed from the Generic tree. They will then be added as children of the new top display and set "usable." (Any children of the traveling objects will naturally move with them.) Traveling objects are most commonly Toolbox Interactions, but they can be any kind of generic object.

Traveling objects can only be used under certain circumstances. Every display must belong to its own object block, and all of these object blocks must be copies of the same original. This is because the traveling objects are added as children to a specified chunk in whichever object block contains the new top display. If you want to use traveling objects, you should declare a special "template" object block which contains a GenDisplay and its children. Whenever you need to create a GenDisplay, you should duplicate this object block. The traveling objects should be in another resource altogether. If you use the Document Control objects to create displays, the objects will use this technique, duplicating an object block for each new display; this will let you use traveling objects.

Every traveling object is indicated by a TravelingObjectReference structure (see TravelingObjectReference ). To attach traveling objects to the active display, create a chunk which contains a list of TravelingObjectReference structures; this chunk must be in the same object block as the active display. Then set the Display's ATTR_GEN_DISPLAY_TRAVELING_OBJECTS to the ChunkHandle of the list. The list will automatically be moved to the block of the active display whenever the traveling objects are moved.

Code Display 4-5 TravelingObjectReference

typedef struct {
    optr		TIR_travelingObject;			/* optr to traveling object whose
					 * reference this is */
    ChunkHandle		TIR_parent;			/* Chunk Handle of object in Display's
					 * block that will be the parent of this
					 * object */
    word		TIR_compChildFlags;			/* CompChildFlags to use when
					 * adding the traveling object */
} TravelingObjectReference;

The TravelingObjectReference structure has the following three fields:

TIR _travelingObject
This field is an optr to the traveling object whose reference this is.
TIR _parent
This field holds the chunk handle of an object in the display block. When the traveling object is added to a display block, it will be made a child of the object whose chunk handle this is.
TIR _compChildFlags
This is the set of CompChildFlags which will be used when attaching this object to its new parent.
| Up: GEOS SDK TechDocs | Up | Prev: 3.2 GenDisplayControl