Programming Guide: Menus

# Programming Guide

## Menus

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:

- Document
- Edit
- View
- Help

### Setting Up Menus

This section describes how your part editor can set up and use menus and menu items.

#### Base Menu Bar

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.

#### Base Pop-Up Menu

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.

#### Adding Part Menus to the Base Menu Bar

When your part initializes itself, or when it first obtains the menu focus, it should create its own menu bar object by:

1. Copying the base menu bar using the window state's CopyBaseMenuBar method.
2. Adding its own menu structures, by using menu-bar methods such as AddMenuBefore and AddMenuLast.

   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.

#### Menu IDs

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.

#### Obtaining the Menu Focus

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.

#### Enabling and Disabling Menus and Commands

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.

#### Menus and Read-Only Documents

When your part permissions (see "Drafts") specify that your document is read-only, your part editor needs to disable these menu commands:

- Cut, Paste, Paste as..., and Delete items in the Edit menu

- any part-specific content-editing 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.

#### Menus and the Root Part

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.

### Document Menu

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.

#### Page Setup and Print document

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.

### Edit Menu

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:

- Undo
- Redo
- Create
- Cut
- Copy
- Paste
- Paste as...
- Links
- Delete selection
- Select all
- Deselect all
- Open selection
- Selection properties

Figure 53 shows the Edit menu.

Figure 53. Edit Menu

View figure.

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.

#### Undo

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".

#### Redo

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".

#### Create

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.

#### Cut, Copy, and Paste

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:

- Operating on parts in addition to intrinsic content. The parts may be represented as frames or icons.

- Making embed versus incorporate decisions.

- Wrapping intrinsic content inside a part in certain circumstances.

Your part should disable the Cut and Paste items when its draft permissions are read-only; see "Menus and Read-Only Documents".

#### Paste as...

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:

1. Acquire the clipboard focus and gain access to its content storage unit, following the initial steps described in "Pasting from the Clipboard".

2. Display the Paste As... dialog box, by calling the ShowPasteAsDialog method of the clipboard object. (For the OS/2 and Windows platforms). Pass the function the active frame into which the paste is to occur.

3. If the method returns kODTrue, the user has pressed the OK button; use the results of the interaction to determine which kind of pasting action to take. Then read the appropriate kind of data from the clipboard, continuing with the procedures shown in "Pasting from the Clipboard".

#### Links

The Links menu item contains the following items.

- Break link. Copies the source information to the document and breaks the link with the source. The action cannot be undone. A confirmation dialog will be given before the link is broken. The Break link choice is for destination links only.

- Paste link. Inserts the link from the clipboard into your part.

  In your routine to handle paste link, you should:

  1. Create an empty "linkspec"
  2. Read in the "linkspec" from the clipboard
  3. Create a link from the "linkspec"

- Link info. Displays the information about a selected link or link source. To handle Link info your routine should display either the ShowLinkSourceInfo dialog (if the selected item is a link source) or the ShowLinkDestinationInfo dialog (if the selected item is a link). Your routine should then respond to any input you supply through the dialog.

#### Delete selection

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 all

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.

#### Deselect all

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.

#### Selection properties

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.

#### Open selection

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:

1. From your private data structures, determine which of your embedded frames is the selected one. (Each embedded part, even if displayed in an icon view type, has a frame).

2. Call the AcquirePart method of the selected frame, followed by the Open method of the part returned by the AcquirePart method. The Open method is described in "Open Method of Your Part Editor".

Your routine should support both single and multiple selection.

### View Menu

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:

- Properties
- Show as
- View in window

Figure 54 shows the View menu.

Figure 54. View Menu

View figure.

#### Properties

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.

#### Show as

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.

#### View in window

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.

### Help Menu

The Help menu choices are as follows:

- Help index
- General help
- Using help
- OpenDoc information

Figure 55 shows the Help menu.

Figure 55. Help Menu

View figure.

#### Help index

Displays the index for OpenDoc help.

#### Using help

How to use the help facility provided with OpenDoc.

#### General help

Displays a general description of OpenDoc.

#### OpenDoc information

Provides OpenDoc version and copyright information.

### Help Menu with Part Help

When you create Part help the following choices are added to the OpenDoc Help Menu:

- MyPart help index
- MyPart help
- MyPart information

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 56 shows the Help menu.

Figure 56. Help Menu with Part Help

View figure.

#### MyPart help index

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.

#### MyPart help

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.

#### MyPart information

A part should provide an information menu item at the bottom of the help menu that displays the author and copyright information.

### Pop-Up Menu

The pop-up menu choices are as follows:

- Properties
- Show as
- View in window
- Help

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.

- View choices (for example, Open as, Properties, and so forth)
- Clipboard/data transfer (for example, Cut, Paste, Delete, and so forth)
- Printing
- Part actions
- Container actions (for example, Align)
- Help

### Accelerator Table Sharing

OpenDoc creates a default accelerator table containing pre-defined accelerator keys for OpenDoc. Parts can add to the accelerator table by following these steps:

1. Fill in an ODACCEL structure with the accelerator information.
2. Call the AddToAccelTable method of the ODMenuBar class.

The AddToAccelTable method can add up to 20 accelerator keys to the accelerator table with each method call.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]