8.7. RFRS Considerations

The "User Interface" section of the RFRS Requirements includes eleven itemsfive requirements and six best practicesdealing with editors. All of them are derived from the Eclipse UI Guidelines.

8.7.1. Using an editor to edit or browse (RFRS 3.5.9)

User Interface Guideline #6.1 is a requirement that states:

Use an editor to edit or browse a file, document, or other input object. This requirement tests that editors are used to edit files (or similar inputs) and views are used to aid navigation (e.g., Navigator) or handle simple modification tasks (e.g., Properties view). Editors must open on double- or single-click (depending on the workbench's single-click behavior preference) from the resource. While views may open simultaneously with the editor, it is improper to open only a view when the input follows an open-save-close lifecycle. Views must not retarget editor actions, contribute to the common toolbar, or otherwise substitute for proper editor behavior and appearance.

For this test, demonstrate the editors provided by your plug-in. Show the file, document, or other input type that they are used to edit or browse. Based on the examples presented in this chapter, show how the Property File editor is used to edit property files.

8.7.2. Editor lifecycle (RFRS 3.5.10)

User Interface Guideline #6.2 is a requirement that states:

Modifications made in an editor must follow an open-save-close lifecycle model. When an editor first opens, the editor's contents should be unmodified (clean). If the contents are modified, the editor should communicate this change to the platform. In response, an asterisk should appear in the editor's tab. The modifications should be buffered within the edit model until such time as the user explicitly saves them. At that point, the modifications should be committed to the model storage.

To pass this test, open your editor on a file and show that the editor is initially unmodified. Then make a change using the editor and show that an asterisk appears in the editor's tab. Finally, save the editor and show that the changes have been committed to the file and that the editor has gone back to its unmodified state. See Section 8.4, Editor Lifecycle, on page 350 for more information about editor lifecycles.

8.7.3. Accessing global actions (RFRS 3.5.11)

User Interface Guideline #6.9 is a requirement that states:

If an editor has support for cut, copy, paste, or any of the global actions, the same actions must be executable from the same actions in the window menu and toolbar. The window menu contains a number of global actions, such as cut, copy, and paste in the Edit menu. These actions target the active part, as indicated by a shaded title area. If these actions are supported within an editor, the editor should hook into these window actions so that selection in the window menu or toolbar produces the same result as selection of the same action in the editor. The editor should not ignore these actions and contribute duplicate actions to the window menu or toolbar. The following are the supported global actions:

1. Undo

2. Redo

3. Cut

4. Copy

5. Paste

6. Print

7. Delete

8. Find

9. Select all

10. Bookmark

Show that your editor supports any relevant global actions such as cut, copy, and paste. Trigger those actions from within your editor and then show that they may also be triggered from the workbench's menu bar with the same effect. For the Properties editor, you would show that global actions, such as delete, can be accessed within both the Properties and Source pages of the editor. See Section 8.5.2.1, Global actions, on page 358 for more about hooking up global actions.

8.7.4. Closing when the object is deleted (RFRS 3.5.12)

User Interface Guideline #6.16 is a requirement that states:

If the input to an editor is deleted and the editor contains no changes, the editor should be closed. When a resource is deleted from one of the navigators (e.g., Navigator view, J2EE view, Data view, or DBA Explorer view in SDP), the handling of any editor that is currently open on that resource depends on whether the editor has any unsaved changes. If the editor does not contain any changes since the resource was last saved then the editor should be immediately closed.

Show that your editor is closed automatically any time an input object to your editor (e.g., a specific resource) is deleted. For the Properties editor, you would create a new properties file, open it with the Properties editor, and then delete the file in the Navigator view. If you implement your editor using the editor framework described in this chapter, the framework should automatically enforce this guideline.

8.7.5. Synchronize external changes (RFRS 3.5.14)

User Interface Guideline #6.30 is a requirement that states:

If modifications to a resource are made outside the workbench, users should be prompted to either override the changes made outside the workbench or back out of the Save operation when the save action is invoked in the editor.

Open your editor on a file and make a change. Next, modify the file outside Eclipse. Finally, switch back to Eclipse and attempt to save the file. Show that you are prompted to override the external changes or to cancel the save operation. If you implement your editor using the editor framework described in this chapter, the framework should automatically enforce this guideline.

8.7.6. Registering editor menus (RFRS 5.3.5.2)

User Interface Guideline #6.14 is a best practice that states:

Register with the platform all context menus in the editor. In the platform, the menu and toolbar for an editor are automatically extended by the platform. By contrast, context menu extension is supported in collaboration between the editor and the platform. To achieve this collaboration, an editor must register each context menu it contains with the platform.

To pass this test, show that your editor's context menus have been registered with the platform. If they are properly registered, you should see the system contributing appropriate context menu items. See Section 8.5.1, Context menu, on page 354 for more about context menus.

8.7.7. Editor action filters (RFRS 5.3.5.3)

User Interface Guideline #6.15 is a best practice that states:

Implement an action filter for each object type in the editor. An action filter makes it easier for one plug-in to add an action to objects in an editor defined by another plug-in.

For this test, show that menu action filtering is in effect for the objects edited by your editor. See Section 6.3.2, Action filtering and enablement, on page 227 for more about using action filters and Section 8.5.1.2, Creating the context menu, on page 356 for more about building context menus that can be extended by other plug-ins.

8.7.8. Unsaved editor modifications (RFRS 5.3.5.4)

User Interface Guideline #6.17 is a best practice that states:

If the input to an editor is deleted and the editor contains changes, the editor should give the user a chance to save the changes to another location, and then close.

Start by opening your editor on a file and then making a change. Next, select the file in the Navigator view and delete it. Show that a warning message is displayed, informing the user that the editor contains unsaved changes. To pass the best practice component of this guideline, the user should be given the option to save the file to another location. If you implement your editor using the editor framework described in this chapter, the framework should automatically enforce this guideline.

8.7.9. Prefix dirty resources (RFRS 5.3.5.5)

User Interface Guideline #6.18 is a best practice that states:

If a resource is dirty, prefix the resource name presented in the editor tab with an asterisk.

This is essentially a subset of Guideline #14. Edit a file with your editor and show that the filename is prefixed with an asterisk. If you implement your editor using the editor framework described in this chapter, the framework should automatically enforce this guideline.

8.7.10. Editor outline view (RFRS 5.3.5.6)

User Interface Guideline #6.20 is a best practice that states:

If the data within an editor is too extensive to see on a single screen, and will yield a structured outline, the editor should provide an outline model to the Outline view. In Eclipse, there is a special relationship between each editor and the Outline view. When an editor is opened, the Outline view will connect to the editor and ask it for an outline model. If the editor answers with an outline model, that model will be displayed in the Outline view whenever the editor is active. The outline is used to navigate through the edit data, or interact with the edit data at a higher level of abstraction.

For this test, open your editor and show that it updates the contents of the Outline view and allows the data's structure to be navigated. If a different instance of your editor is selected, show that the Outline view's contents change appropriately. See Section 8.4, Editor Lifecycle, on page 350 for information about linking an editor to the Outline view.

8.7.11. Synchronize with outline view (RFRS 5.3.5.7)

User Interface Guideline #6.21 is a best practice that states:

Notification about location between an editor and the Outline view should be two-way. Context menus should be available in the Outline view as appropriate.

Select an item in the Outline view and show that it selects the corresponding item in the editor. Next, select an item in the editor and show that it selects the corresponding item in the Outline view.