Programming Guide

Controls

This section discusses what kinds of controls you can construct, and how to handle events within controls. It also discusses two specific issues for palettes: how to share them among instances of your part, and how to use them to embed parts within your part.

Design Issues for Controls

Controls in OpenDoc have the same function as in conventional applications: they are graphical objects that allow you to interact with and manipulate documents in a variety of ways. However, there are some differences:

• In a conventional application, controls typically apply to the entire document. They are always present unless dismissed explicitly. In an OpenDoc document, however, each part may have its own set of controls, and thus controls can appear and disappear rapidly as you edit. This rapid change can be irritating if not carefully managed.  

• In a conventional application, finding the space in which to display a control may be less of a consideration than in OpenDoc. It may be a challenge for small embedded parts to find sufficient space to display rulers, scroll bars, and palettes.

• In OpenDoc, controls can be constructed as independent parts, assemblages of parts, different frames of a single part, or content elements of a part. This can give you more flexibility in constructing user-interface elements than is possible for conventional applications.  

• OpenDoc controls can have attached scripts or can communicate with each other, or with other parts, using the OpenDoc extension mechanism. This gives OpenDoc controls the ability to be far more integrated and context-sensitive than standard controls.

Standard types of controls you might wish to include with your parts include:

• Push buttons, radio buttons, and checkboxes
• Scroll bars and sliders, or other gauges
• Pop-up menus
• Rulers
• Tool bars
• Palettes

Rulers usually reflect some settings of the current selection context and contain controls that allow you to change these settings. Tool bars are like rulers but they often trigger actions instead of changing settings. Status bars display the progress of some long-running operation or suggest actions to users.

In conventional applications, rulers and tool bars commonly occupy the margins of the window. In an OpenDoc document, controls can be displayed at the margins of the window, in separate frames outside the embedded frame they apply to, or within the frame they apply to.

A ruler for a text part, for example, can be an additional frame associated with the part. Events in the ruler are handled by the part's editor. Alternatively, the ruler may be its own part with its own editor. In this case, the text part editor must maintain a reference to the ruler part and be able to communicate with it through semantic events or some other extension mechanism.

A ruler that is a separate part can have its own embedded parts, such as buttons. The ruler part must then be able to communicate with its embedded controls as well as with the part that it services.  

Palettes often contain editing tools but can also contain choices for object attributes like color or line width. Palettes commonly float freely beside or over the document, although they can also be fixed at the window margins. Palettes might also pop up, pull down, or be torn off of menus.

If all parts in a document can communicate with each other, they can coordinate the drawing and hiding of palettes or other controls to avoid irritating the user. For example, all parts in a document can share a single palette, within which the various parts negotiate for space and in which they draw only those tools that must change as the active part changes.

Handling Events in Controls

How you handle events in a control depends on how you design the control:

• If a control like a ruler is within the active frame, it might not have its own frame, and the active part editor handles any events in the ruler.

• If a control has its own frame, it might be another display frame of the active part. In this case also, the active part editor handles the event in the control.

• If a control is a separate part, its own part editor handles the event and updates the state of the part, which might trigger scripts or calls to other parts' extension interfaces. Likewise, the part itself can receive queries from other part editors in the form of semantic events or calls to its extension interface.

Sharing Palettes and Utility Windows

The user-interface guidelines state that you should hide any visible palettes, modeless dialog boxes, or other utility windows when your part becomes inactive or its document closes. When the part becomes active or the document reopens, you should restore them in the same positions. In addition, if your part editor maintains multiple parts in a document and the active state switches from one to another of them, any visible utility windows that apply to both parts should remain steadily visible, without any flicker caused by hiding and immediate restoring.

One way to implement this behavior for a utility window is to follow, in general, steps such as these:

• Make the window globally accessible to your parts by keeping its reference and its state in an object that each of your parts acquires on initialization and releases on closing.

• Have the global object create the window in a normal manner the first time it is to be displayed. When you close the window, the global object can simply hide it by calling its Hide method. If you subsequently need to display the window again, the global object can show it again by calling its Show method.

• When your part relinquishes the selection focus, its CommitRelinquishFocus method can check to see if the part that is receiving the focus also belongs to your part editor, and has a presentation that uses the same utility window. There are a number of ways to check this, such as by examining the presentation, part info, or even the part kind associated with the newly active frame.

• When your part acquires the selection focus, it notifies the global object of that fact. The global object, in turn calls the ChangePart and SetSourceFrame methods of the utility window's frame to assign the new part and frame to the utility window. The new part can then adjust the content of the utility window if needed, and also show or hide other palettes or dialogs.

Using a Tool Palette to Embed Parts

An example of an OpenDoc-specific use for controls is to allow you to embed parts by selecting items from a palette. Using a palette in this way, your part can create embedded parts from scratch, rather than through reading in existing part data.

Your part can provide a palette, menu, or dialog box from which you select an item that specifies a part kind. As in many conventional applications, your palette could display a set of tools to the user. These user tools are for drawing, painting, text and so forth. In this case, however, selecting an item from the palette actually means that a new part of that kind is to be embedded in your part.

The items could represent existing stationery documents in the user's system, or they could simply represent individual part kinds for which editors exist. If you are creating parts from scratch, follow steps such as these once your have made a selection from your palette:

• Create the new part by calling your draft's CreatePart method, passing it the part kind that you selected.

• Call the new part's Externalize method (see "The Externalize Method"), so the part can create and write initial data to the properties in its storage unit.

• Create a new embedded frame for the part, as described in "Creating a New Embedded Frame".

• Give the new frame the proper link status, as described in "Frame Link Status".

• If the new frame is visible, assign facets to it, as described in "Adding a Facet".

• Notify your containing part and your draft that there has been a change to your part's content; see "Making Content Changes Known".