Programming Guide

Mouse Events, Activation, and Dragging

This section discusses how your part should respond to mouse-down, mouse-up, and activate events in order to activate your part or your window, initiate a dragging operation, or create a selection. Your HandleEvent method (see "HandleEvent Method of Your Part Editor") should dispatch events to routines that perform the actions described here. For other information about creating and modifying selections, see "Mouse-Down Tracking and Selection".

How Part Activation Occurs

A part's frame activates itself in these situations:

• When it receives a mouse event within its content area

• When its window first opens and the part has stored information specifying that the frame should be active on opening

• When its window becomes active and the part has stored information specifying that the frame should be active upon window activation

• When data is dropped on the part as a result of a drag-and-drop operation

• When it has another reason for becoming active (such as the need to display a selection, such as a link source, to the user)

The part activates itself by acquiring the selection focus (see "Focus Types") for one of its display frames. The part is then responsible for displaying its contents appropriately (such as by restoring the highlighting of a selection) and for providing any menus, controls, palettes, floating windows, or other auxiliary items that are part of its active state. The part must also obtain ownership of any other focuses that it needs. OpenDoc draws the active frame border around the frame with the selection focus. Figure 49 illustrates some of the visual changes caused by activation.

Figure 49. Inactive and Active States of a Part

View figure.

In Figure 49, the graphics part is active. OpenDoc draws the active frame border around its frame.

Typically, one part is deactivated when another is activated. A part is expected to deactivate itself when it receives a request to relinquish the selection focus, plus, possibly, other focuses. The deactivating part is responsible for clearing its selections and for removing any menus and other items that were part of its active state.

Note:

An active part in the active window should not maintain a background selection.

Mouse events that cause part activation can also cause window activation and can lead to dragging of part content. Figure 50 illustrates elements you must consider in handling mouse-down events. Your part should handle mouse events according to:

• Whether your part is active or inactive.

• Whether it is in an active or inactive window.

• Whether the event location corresponds to one of the elements.

Figure 50. Elements Related to Mouse Events in Active and Inactive Windows

View figure.

Note these points from the previous figure:

• Embedded parts can be represented by either frames or icons. Frames can be active or inactive, and inactive frames can be either selected or unselected. (Not shown in the figure is that inactive frames can also be bundled).

• There can be only one active frame in the active window, and no active frame in an inactive window (except that a dialog box can appear in front of a window that contains the active part).

• All selected items must be within the active frame.

• A selection in the active window becomes a background selection if the window becomes inactive.

• A selection (either foreground or background) can consist of either intrinsic content or an embedded frame or icon, or a combination of both.

• "Click-selectable intrinsic content" in the figure means any item of intrinsic content that can be selected by a single mouse click, such as a graphic object in a draw part.

• "White space" in the figure means any location in the content area of a part that is neither click-selectable intrinsic content nor an embedded part frame or icon. It includes empty space, but also includes content (such as text or painting) that requires a sweeping gesture, rather than a single click, for selection.

• An inactive window may be in the current process (if, for example, it is a part window of the active document) or in a background process (if, for example, it is a window of another document).

The event-handling guidelines given here are designed to provide the user with maximum consistency and flexibility when activating parts and when dragging selections.

Handling Mouse Events

Mouse events are typically sent to your part's HandleEvent method as normal mouse messages for your operating system. Events in embedded frame or its border may be converted into synthetic OpenDoc events such as kODEvtMouseDownEmbedded of kODEvtMouseDownBorder events. For converted events, the /BEGIN-ITALICS/ originalType /END-ITALICS/ field of the EventInfo structure will contain the event type of the original mouse message.

Handling Activate Events

As noted in "Activate Events", your part receives an activate event for each of its facets when your window becomes active, and a deactivate event when your window becomes inactive.

When a window becomes inactive, the part that holds the selection focus is likely to relinquish that focus (on request by another part) but can still maintain, as a background selection, any selection it had been displaying. Conversely, when a window becomes active, the part that had held the selection focus when the window became inactive normally regains the selection focus. That part may or may not be the part that actually activated the window.

This part-activation convention requires that your part respond to activate and deactivate events by recording or retrieving stored information on its focus transfers; see "Window Activation" for more information.

Activate events in a window go first to the most deeply embedded facets and last to the root facet. This dispatch order gives the root part the opportunity to obtain the selection focus if no embedded part has done so. It also allows the root part to override any activation actions taken by embedded parts.