Eclipse UI Best Practices v3.x Updates

This document provides drafts of ongoing updates to the Eclipse v3.x UI Best Practices. We have decided to use a new format to document UI design guidelines for Eclipse v3.x. It's designed to help practitioners apply the UI design quicker and easier.

Notice

Your feedback can influence the ideas and best practices described here. If you have suggestions, please provide us with your feedback on the UI mailing list or on the discussion page.

Limit Context Menus

Summary

Remove extra items from context menus on objects in editors and views.

Problem Description

A context menu provides a quick and convenient way to give a user access to a great deal of functionality. Unfortunately, it is tempting to add too much functionality to an object’s context menu. The resulting menus can become overly long and complicated, which slows down the efficiency of a user’s work with the product. Moreover, it is possible to create the same context menu for all objects, regardless of type, within an editor or view. Such uniformity deprives a user of subtle feedback about which type of object they are currently working with. Contextual feedback is needed for a user to have a clear sense of the functionality of each object type.

Best Practice

There are at least three ways to trim an object’s context menu, so that it will be quick to scan and well targeted at the object.

First, remove menu items that don’t apply to the object at all. This may sound obvious, but in a complicated product environment, it is easy for unrelated items to creep into a context menu. Of course, a menu item that doesn’t apply could be grayed out. But if it never applies, it’s better to remove the item entirely. For example, it would be confusing to have a “Run as” item on the context menu of a C++ header (.h) file in a navigator-style view, since run operations really apply to code instead.

Second, remove items that apply only to the view or editor as a whole. While a user may find it convenient to access these items from an object, it is better to have a “lean and mean” context menu instead – one that is uncluttered and focuses attention on the object at hand. Access to actions related to the view or editor as a whole are better handled by right clicking on the white space outside any object (or by clicking on the view menu). The user will get a better sense of the view or editor as a whole, without any confusion about what menu item lives where. For example, view preferences should not be on the context menu for an object in that view, but rather on the context menu outside any object (or in the view menu).

Finally, remove items from an object’s context menu that apply to other, nearby objects, but not to the specific one in question. The resulting menus will make more sense to the user, as the actions logically appropriate to the object will be there, but not actions logically appropriate to some other type of object. For example, it would be confusing to have a “Close Project” item on the context menu of a Java method shown in an explorer view, since import operations apply at the project level instead.

Tips and Tricks

Sometimes there is value in adding a view-specific item to an object’s context menu, if the action of the menu item can be customized in some way for the object. For example, a generic “New” menu item might open up a new editor pre-populated with item(s) related to the selected object.
Be sure to keep the item order on a context menu as similar as possible for different types of object. This similarity will maximize consistency for the user.

In cases where it is not possible to reduce the number of items on a large context significantly, consider using submenus to refactor some top-level items to the second level.

Good Examples

Figure 1: a context-dependent menu tailored for a package in the Outline View.

Figure 2: a context menu tailored for a class in the Outline View.

Figure 3: a context-independent menu for the Outline View.

Related Information

This issue is addressed in the Eclipse UI Guidelines 2.1, in the section titled “Component Development - Editors” (Guidelines 6.11-6.13).

UI Graphics

OVERVIEW

The following guide covers user interface (UI) graphics for Eclipse 3.x-based tools. All visual user interface elements created for Eclipse-based tools follow a common style called the Eclipse visual style or Eclipse style. Any product, tool, or plug-in based on the Eclipse Workbench Version 3.0 and above should follow these guidelines to help ensure consistency of visual user interface elements. Consistency includes visual style, meaning, and implementation conventions.

SPECIFICATIONS provides detailed information on color palette, graphic types, size and placement of the graphics in their alotted real estate, and positioning of the icon and wizard graphics in the user interface.

IMPLEMENTATION provides automated cutting actions, conventions for file and folder naming and structure, and code snippets for implementing icon states on the toolbar and local toolbar and for placing overlays on model objects.

Audience

These guidelines are for anyone creating Eclipse style user interface graphics or seeking best practices for their use. This is not a how-to guide, but you will find instructions for some tasks and a number of resources to assist in making the graphics. If you are a designer, you will be interested in the Design, Specifications, and Implementation sections. If you are a Developer, the Specifications and Implementations sections will be of most value to you.

Consistency & Reuse encourages consistency and reuse of existing graphical elements, and shows the core icon and wizard concepts currently in the tools.

Common Elements provides a library of graphical elements that have already been developed for Eclipse-based tools. This extensive selection of common elements provides not only a base for creating new icons and wizard graphics, but for reusing existing ones as they are. Used in conjunction with the core concepts shown in the Consistency & Reuse section, this library will enable efficient creation of graphical elements and promote consistency throughout the user interface.

States describes the use of enabled and disabled icons in the user interface. It also provides instructions and an automated action set for creating the disabled state of your enabled color icons, a useful tool when producing a large volume of icons.

Templates provides design files for producing different types of user interface graphics. A description of the templates and guidance on how to work with them is provided to help you get started quickly and working effectively.

SPECIFICATIONS

This section details technical information you will need to design and prepare your Eclipse-style graphics for implementation.

File Formats lists and describes the graphic file formats used for the different graphic types.

Graphic Types describes the different types of graphics that are used in Eclipse-based tools, and where they are located within the user interface.

Icon Size & Placement shows the final cut size of each of the different types of icons, as well as what the placement and drawing area is within the allotted space.

IMPLEMENTATION

This section provides automated cutting actions, and conventions for file and folder naming and structure.

Cutting Actions describes the macros for cutting icons, icon overlays, and wizard banner graphics to get them ready for implementation.

Naming Conventions describes the Eclipse standard for file naming and guidelines for using suffixes that will help others quickly identify the graphic type or function.

Folder Structure provides the Eclipse standard for folder names and structure for storing and implementing graphics within your plugin.