View figure.
At any given moment while an OpenDoc document is open, responsibility for the menu bar is shared between two entities. The OpenDoc document shell creates the Document menu, Edit menu, and Help menu. Individual part editors can create other menus as needed. (Part editors can also, with restrictions, add appropriate items to the Document and Edit menus).
Different platforms have different conventions for enabling and disabling menus and menu items. In an OpenDoc document, the document shell, the root part, and the part with the menu focus together control which menu commands are available. As each part becomes active, the OpenDoc document shell and the root part update their own menu items, and the active part editor takes care of the rest.
Basic event handling for menu events is described in "Menu Events". When you select a menu item, the document shell either handles the command itself or dispatches a menu event to the active part; the part receives the event as a call to its HandleEvent method.
This section discusses general issues of setting up and working with menus and then describes how to handle individual menu events for the standard OpenDoc menus:
This section describes how your part editor can set up and use menus and menu items.
When it first opens a document, the document shell creates a menu bar object (type ODMenuBar) and installs it as the base menu bar by calling the window state's SetBaseMenuBar method. The base menu bar contains different menus and items on different platforms, but the Document menu, the Edit menu, the View menu, and the Help menu are always installed.
The document shell also creates a pop-up menu object (type ODPopup) and installs it as the base pop-up menu by calling the window state's SetBasePopup method. The base pop-up menu always installs the Properties, Show as, View in window, and Help menu items.
When your part initializes itself, or when it first obtains the menu focus, it should create its own menu bar object by:
On the Windows platform, menus that are being added, that have pull-down menus in them, should use the AddMenuBeforeEx and AddMenuLastEx menu-bar methods.
If absolutely necessary, your part editor can add items to the end of the Document and Edit menus, but you should not alter the existing items.
You must identify each menu with a menu ID. A menu ID is a positive short value.
All menus and menu items in the menu bar must have unique menu IDs.
Therefore the document shell, the active part, and any shell plugs-in
or services that also have menus must cooperate to ensure that there
are no conflicts. Trying to add a menu item ID or a menu that
contains a menu item ID that already exists results in an exception
being thrown.
Please follow the conventions listed in
Table 4
list to ensure that your menu IDs do not conflict with
those of others.
Table 4. OpenDoc Menu ID Ranges
| Type of Software | Menu ID Range |
|---|---|
| Document shell | 0x0000 - 0x2FFF |
| Part editors (when root) | 0x3000 - 0x3FFF |
| Shell plug-in/services | 0x4000 - 0x4FFF
Note: These menu IDs must be dynamically assigned. |
| Part editors | 0x5000 - 0x7FFF |
A shell plug-in or service may have to adjust its menu ID dynamically at runtime, because another service or plug-in with that menu ID may already be installed. The plug-in should choose an ID, look for an installed menu with that ID, and, if found, add 1 to the ID and try again.
When your part activates itself, it should request the menu focus (along with other focuses) if it wants to use menus. See "Requesting Focuses" for more information.
When you click in the menu bar, OpenDoc determines which part has the menu focus and calls that part's AdjustMenus method. It also calls the root part's AdjustMenus method, if the root part does not have the menu focus.
Your part's AdjustMenus method can use methods of the menu bar object such as EnableMenuItem or CheckMenuItem to change the appearance of your menu items, or it can make platform-specific calls to directly enable, disable, mark, or change the text of its menu items.
Your AdjustMenus method typically acquires the clipboard focus and enables the Cut, Copy, Paste, and Paste as... items in the Edit menu.
When your part permissions (see "Drafts") specify that your document is read-only, your part editor needs to disable these menu commands:
This situation can occur when you view a previous draft of a document, or when a document is stored on read-only media.
Part viewers should disable these items and commands at all times.
In all OpenDoc documents, the root part is responsible for printing. The root part therefore should handle the Page Setup and Print document items from the Document menu, even if an embedded part has the menu focus.
To allow the root part access to menu events, they are passed to the root part if they are not handled by the part with the menu focus. Also, OpenDoc calls the root part's AdjustMenus method before it calls the AdjustMenus method of the part with the menu focus, so that the root part can adjust the state of those menu items.
When your part's AdjustMenus method is called, it should check to see if your part is the root part and whether it has the menu focus. If it is the root part but does not have the menu focus, it should adjust only the Page Setup and Print document items from the Document menu. If it is an embedded part with the menu focus, it should not adjust those items.
Likewise, when your part's HandleEvent method is called, it should first check to see if your part is the root part. If it is the root part, HandleEvent should return false if it is passed any menu events other than the PageSetup and Print document items in the Document menu. If it is an embedded part, HandleEvent should return false if it is passed Page setup or Print document.
This section describes how your part editor should interact with the Document menu. The OpenDoc document shell handles most Document menu commands, as described in "The Document Shell and the Document Menu". Individual part editors must respond only to the Page setup and Print document commands.
The root part of the window handles the Page Setup and Print document commands. Root parts are responsible for defining the page size, characteristics, and the printing behavior of their documents. When you choose one of these commands and your part is the root part of the active window, OpenDoc passes the kODCommandPageSetup or kODCommandPrint command to your part's HandleEvent method.
Most items in the Edit menu are handled by individual part editors. Most apply to the current selection in the currently active part.
Choices on the Edit menu are as follows:
Figure 52 shows the Edit menu.
Menu items can vary depending on the part displayed. In this case Imbed and Options were added to the menu bar by the part selected. Under Edit, the menu items Move, Move To Front, Move To Back, and Resize were added by the selected part. Each item is explained in detail in the following sections.
Select Undo from the Edit menu in order to reverse recently enacted user actions, including previous uses of Redo. Undo reverses the effects of the last undoable user action and restores all parts to their states before that action. Not all user actions are undoable. OpenDoc supports multiple levels of Undo. For example, if you select Undo three times in succession, then the last three undoable actions are undone in order.
The document shell handles the Undo item, passing control to the Undo object. The Undo object, in turn, calls the UndoAction method of any part editors involved in the Undo.
Your part should respond to Undo as described in "Undo".
Select Redo from the Edit menu in order to reverse the last use of Undo. Redo is available only if the last undoable user action was Undo or Redo. Redo reverses the effects of the last undoable user action, restoring all parts to their states before the Undo action. OpenDoc supports multiple levels of Redo. Each time you select Redo, the previous Undo is redone. This works only if you invoked Undo multiple times in succession.
The document shell handles the Redo item, passing control to the Redo object. The Redo object, in turn, calls the RedoAction method of any part editors involved in the Redo.
Your part should respond to Redo as described in "Undo".
Select Create to create a new part of the same type as the selected part. The part will be created on the clipboard. When Create is selected, the Paste link menu item and the Paste Link push button in the Paste As... dialog should be grayed because linking is not possible at this point.
Select Cut, Copy, or Paste from the Edit menu in order to place data onto the clipboard or retrieve data from the clipboard.
The Cut, Copy, and Paste choices are familiar mechanisms for copying and moving content around in the system. In OpenDoc, function has been added for handling embedded parts. The function added consists of:
Your part should disable the Cut and Paste items when its draft permissions are read-only; see "Menus and Read-Only Documents".
Select Paste as... from the Edit menu in order to specify the manner in which clipboard data is to be pasted into the active part.
On the OS/2 platform and on the Windows platform, the Paste as... choice displays a dialog box that allows you to specify the data format for pasting the clipboard into the destination. The clipboard content is converted to the user-specified format, and links to it can be created. When you select the command, OpenDoc passes the command information to your part's HandleEvent method.
To handle the Paste as... command, your routine should prepare to read from the clipboard, like this:
The Links menu item contains the following items.
In your routine to handle paste link, you should:
Select Delete selection to delete the selected content from the active part.
Your routine to handle the Delete selection command should remove the items that make up the selection from your part content. That may involve deleting embedded parts as well as intrinsic content.
Select Select all from the Edit menu to make the current selection encompass all of the content of the active part.
Your routine to handle the Select all command must include all of your part's content in the selection structure that you maintain and it must highlight the visible parts of it appropriately.
Select Deselect all from the Edit menu to deselect all the content of the active part.
Your routine to handle the Deselect all command must include all of your part's content in the selection structure that you maintain and it must highlight the visible parts of it appropriately.
Select Selection properties from the Edit menu to display the standard information about a selected embedded part. If more than one part is selected, this option is disabled. OpenDoc passes the command information to your active part's HandleEvent method. Your routine to handle the Selection properties command should display the Properties notebook that describes the characteristics of the current selection.
When handling Selection properties, if the current selection is an embedded frame border, display the properties for the part in that frame using the ShowPartFrameInfo method of the info object (class ODInfo). Obtain a reference to the Info object by calling the session object's GetInfo method. OpenDoc handles all changes made by the user and updates the information in the storage units for the embedded part and frame, including performing any requested translation.
OpenDoc determines the information it displays by reading the part's Info properties. The set of properties, separate from the part's contents, can be displayed and possibly changed by the user. All stored parts include them. If your part creates an extension (see "The Settings Extension"), it can define and display additional properties.
Select Open selection from the Edit menu to open the selected embedded parts within a window. When you choose this command, OpenDoc passes the command to your active part's HandleEvent method. Your routine to handle Open selection should do the following:
Your routine should support both single and multiple selection.
The View menu shows the views of the active part. If your part editor supports different views of part content in a frame or allows multiple simultanious views, then update the View menu. Add items to invoke your Part's view support. The default View choices are as follows:
Figure 53 shows the View menu.
Select Properties from the View menu to display a Properties notebook for your part. The Properties notebook is displayed for your frame using the ShowPartFramInfo method of the ODInfo class associated with your part. Obtain a reference to the info object by calling the session object's GetInfo method. OpenDoc handles all changes made by the user. This menu item is disabled by default. Your part editor must enable it if it supports this function.
Select Show as from the View menu to change the view type of your part's frame. The default view types are Large Icon, Small Icon, Thumbnail, and Frame. Your part should call its SetViewType method, passing the view type selected. This submenu is disabled by default. Your part editor must enable it if it supports this function.
Select View in window from the View menu to display the active part in its own part window. This menu item is disabled by default. Your part editor must enable it if it supports this function. When this item is selected, OpenDoc passes the command information to your active part's HandleEvent method.
The Help menu choices are as follows:
Figure 54 shows the Help menu.
Displays the index for OpenDoc help.
How to use the help facility provided with OpenDoc.
Displays a general description of OpenDoc.
Provides OpenDoc version and copyright information.
When you create Part help the following choices are added to the OpenDoc Help Menu:
Note:
On the Windows platform the help text source is in RTF format and should be compiled using the hcw compiler. On the OS/2 and AIX platforms the help text source is in IPF format and should be compiled using the IPFC compiler.
Figure 55 shows the Help menu.
Figure 55. Help Menu with Part Help
Displays the index for your part. When a part receives a "MyPart help index" menu event, it should display its index by calling the DisplayHelpIndex method of the ODHelp class. A part obtains a reference to the ODHelp class by calling the GetHelp method of the ODSession class.
Note:
A part does not need to add an index menu item if the help content is small.
Displays general help for your part. When a part receives a "MyPart help" menu event, it should display its general help by calling the DisplayHelp method of the ODHelp class. A part obtains a reference to the ODHelp class by calling the GetHelp method of the ODSession class.
A part should provide an information menu item at the bottom of the help menu that displays the author and copyright information.
The pop-up menu choices are as follows:
Additional actions that a part can perform should also be listed in the pop-up menu. Related choices should be grouped together. The commands generated from the pop-up menus are the same as those generated from the menu bar.
OpenDoc creates a default accelerator table containing pre-defined accelerator keys for OpenDoc. Parts can add to the accelerator table by following these steps:
The AddToAccelTable method can add up to 20 accelerator keys to the accelerator table with each method call.
View figure.
View figure.
View figure.