View figure.
Most part editors interact with the user primarily by responding to user events. User events are messages sent or posted by the operating system in response to user actions, activation or deactivation of a part or window, or messages from other event sources. Based on information in a user event, a part editor might redraw its part, open or close windows, perform editing operations, transfer data, or perform any sort of menu command or other operation.
OpenDoc has several built-in event-handling features that help your part editor function properly within a compound document. For example, instead of polling for events, as a typical application does, your part editor acts when notified by OpenDoc that an event has occurred.
This section notes some of OpenDoc's event-handling features; for more information on user events, see "User Events".
Part editors respond differently to user events than conventional applications do. Part editors do not receive events directly; OpenDoc receives them and dispatches them to the proper part editor.
Because they are not complete applications, and because they must function cooperatively, part editors run in an environment that itself handles some of the tasks that conventional applications typically perform. That environment is called the OpenDoc document shell; it is an executable that handles certain application-level tasks and provides an address space for each OpenDoc document within which part editors manipulate document content.
Whenever an OpenDoc document is opened, OpenDoc creates an instance of the document shell. The shell creates global objects and uses them to open the document. OpenDoc then loads the part editors for all parts that appear in the document window; the part editors read in the data of their own parts. The shell receives both user events and scripting-related events See "Scripting Support". The shell uses the OpenDoc dispatcher to dispatch those events to the proper part editors, based on event location and ownership of shared resources such as menus.
The document shell is described in "The Document Shell". How the dispatcher sends events to parts is described in "User Event Handling".
As a result of user actions or commands, OpenDoc interacts with part editors to perform these common application activities:
In general, the document shell receives events and passes the appropriate information to the proper part editor.
In response to user actions, individual parts in a document become active and thus editable. A part is active if it possesses the selection focus; the user can select and modify its contents in this state. The active part may also possess the menu and keystroke focus; see "Focus Transfer" for more information on focuses.
Parts activate themselves in OpenDoc, and the individual parts in a document must cooperate to transfer the selection focus among each other as appropriate. Note that when a part is not in the active (editable) state, it need not be idle; multiple parts within an OpenDoc document can perform different tasks at the same time.
Switching among individual parts within a document can involve a much less intrusive context switch than switching from one conventional application to another. Users are less likely to be irritated, because the wait before they can edit a newly activated part is not all that perceptible.
The active state is different from the selected state. When a part is selected, its frame is made available for manipulation. Because embedded frames are considered to be content elements of their containing part, they can be selected and then moved, adjusted, cut, or copied just like text, graphic objects, or any other content elements. Where an active part is manipulated by its own part editor, a selected part is manipulated, as a frame, by its containing part. The following figure shows the visual differences among the inactive, selected, and active states of an embedded part.
Figure 11. Inactive, Active, and Selected States of an Embedded Part
An inactive part, one that is not being edited, need not have a visible frame border. A selected part's frame border is drawn by the containing part; its shape typically corresponds to the frame shape, and its appearance should follow guidelines for selected frames. An active part's frame border is drawn by OpenDoc; its shape corresponds to the active shape of the embedded part's facet, and its appearance is fixed for each platform.
When a part activates, more than its own frame border changes. The following figure illustrates some of the visual changes to a window caused by part activation.
Figure 12. Inactive and Active States of a Graphics Part (Shown on OS/2)
In the figure, the text part is active first. OpenDoc has drawn the active frame border around its frame, it has a highlighted selection, and it displays its own menus. Then the text part becomes inactive and the graphics part becomes active. The text part removes its menus and its highlighting. The graphics part displays its own menus and also displays a palette, in separate windows. (OpenDoc in this case does not draw the active border around the graphics part's frame, because the graphics part is the root part.)
Activation generally occurs in response to mouse clicks within the area of a frame (specifically, within the area of a facet's active shape). OpenDoc follows an inside-out activation model, in which a single mouse click causes activation of the smallest (actually, the most deeply embedded) enclosing frame at the pointer location. In the case of a deeply nested embedded frame, as shown in the following figure, a single click within the frame of the most deeply embedded part activates that part and allows the user to start editing immediately.
Figure 13. Inside-Out Activation of a Deeply Embedded Part (Shown on OS/2)
By contrast, some compound-document architectures use an outside-in activation mode, in which the user selects the outermost (nonactive) frame with one click and activates it with the second click. Thus, many clicks might be necessary for the user to activate a deeply embedded part. In Figure 13, for example, the user would have to click four times to start editing.
Despite the advantages of inside-out activation, a containing part may at times not want an embedded part to be activated when the user clicks within its frame; it may instead want the part to become selected. For example, if the user can move but not edit a part embedded within your part, you can specify activation by selection instead of by mouse click. OpenDoc allows you to specify this behavior for an embedded part by placing its frame in a bundled state. A bundled frame acts like a frame with outside-in selection, in that a single click selects the frame. However, unlike with outside-in selection, subsequent clicks do not then activate the part; you have to unbundle it before it can be activated.
Your part does not receive window-activation events directly. The OpenDoc dispatcher notifies your part when its window becomes active or inactive, as described in "Handling Activate Events". It also notifies the containing part, rather than the embedded part, when an embedded part should become selected.
Menu organization and menu handling are different on different platforms. OpenDoc encapsulates certain aspects of menu behavior in a platform-neutral menu bar object. That object gives your part editor access to its own and to OpenDoc's menus.
There are three menus that are available whenever an OpenDoc document is active. It is recommended that these menus remain unchanged by the part editor, with the exception of adding more choices. The part is free to put up as many other menus as desired by the developer.
The standard menus are:
The Document menu contains choices that affect the top-level part shown in the window.
This menu contains standard choices on selected parts or selected intrinsic data. For example, there are options to create a new part of the same type as the selected part and to undo and redo user actions.
In addition to the menu bar, each part has a pop-up menu. The only difference between the pop-up menu and choices in the menu bar menu is that in pop-up menus unavailable choices are not shown. Unavailable choices are grayed in menu bar menus.
More information on the individual menus is in "Menus".
Most of the items in the Document menu are handled by the document shell; see "The Document Shell and the Document Menu" and "Document Menu" for more information.
Your part editor can add menus of its own, and it can modify, within strict limits and according to certain rules, the standard OpenDoc menus.
Applications on many platforms provide a form of undo, a capability that allows a user to reverse the effects of a recently executed command. OpenDoc provides better support for undo than do most current platforms by allowing multiple sequential undo actions. The user can undo multiple sequential commands, rather than only one.
OpenDoc support for undo is described in more detail in "Implementing Undo".
View figure.
View figure.