UI Best Practices v3.x
- 1 Eclipse UI Best Practices v3.x Updates
- 1.1 Notice
- 1.2 Top Ten
- 1.3 General UI Guidelines
- 1.4 Component Development
- 1.5 UI Graphics
- 1.6 Resources
- 1.7 Guidelines
Eclipse UI Best Practices v3.x Updates
These updates have been merged with the Eclipse 2.1 UI Guidelines document.
- THIS CONTENT WILL BE REMOVED ONCE THE MERGE IS COMPLETE***
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.
This is a starter set of top ten Eclipse UI Guidelines and Violations. The purpose of these lists is to be a starting point for Eclipse UI designers and developers, providing the most important practices to follow and to avoid, respectively.
To see all considerations to-date go to the Top Ten Lists Working Page.
Top Ten Eclipse UI Guidelines
- Use the Eclipse look and feel if extending or plugging into Eclipse
- Use common SWT controls to get what SWT offers for cross-platform adaptability and accessibility
- Be familiar with APIs for the UIs you are building
- Use icons and graphics consistent with the Eclipse style, decorations, states, and quality
- Understand the conventions of the OSs you are developing for
- Use understandable messages to help people recover from error conditions
- Don't initiate dialogs or wizards in an error state
- Use quick fix and quick assist mechanisms
- Reserve time for "polish"
Top Ten Eclipse UI Violations
- Low quality graphics or not consistent with the Eclipse style
- Poorly organized or sized dialogs and wizards
- Useless dialogs
- Cryptic error messages
- Messages with concatenated strings
- Property pages that don't adhere to platform uses (normal and tabbed)
- Assuming more importance than other contributions (see John/Mik comments below)
General UI Guidelines
Common Error Messages
Use the common structure of error messages to help users diagnose and recover from errors. This will increase user’s self-sufficiency and reduce support costs for Eclipse-based products.
Across Eclipse-based products, error messages are displayed inconsistently. This inconsistency makes it difficult for users to understand error conditions, and to diagnose and recover from problems.
Eclipse-based products should help users to diagnose the underlying problem when one of our error messages is displayed. We need to consolidate, transform or coordinate errors bubbled up through various sub-systems or dependent components. For example, users would currently see a (cryptic) SQL error message when they have provided an incorrect userid or password for a SQL query. In this case, users would have no idea how to fix this problem or where to look for possible solutions. In the ideal scenario, if our tools coordinate or transform the error code returned from DB2, and inform users that there's a problem with the supplied userid or password, we would provide a good experience for our users. We should generally leverage the symptom database for diagnoses and error recovery. One possible approach for the error message transformation or coordination is this: leverage the common error message logging facility. That is, use CBE infrastructure in code to log all error or warning conditions.
[ TODO: need more detailed info on the Eclipse v3.3 error message infrastructure...TBD ]
Apply the four components of the format for common error messages, to make these messages easily understood by users and to ensure consistency. Each error message should include the following four main components:
• message ID
• message text
The message ID provides a quick means to distinguish one message from another. The message text briefly describes the problem. The explanation includes the reason that the message was generated and the condition that caused the message. The action suggests ways to resolve the problem. Error messages are intended for end users; with this in mind, we should transform programmatic error text into user-comprehensible description in most cases.
For error messages shown in the user interface (UI), do not show the message’s ID, but make it accessible. UI error messages are intended for end users, not developers. Therefore we should not intimidate end users with a (cryptic) message ID that add no immediate value to their understanding of the error condition. However, we should make the unique message ID accessible in the detailed explanation of the message, so that users can search on the Web using the message ID, or submit the ID to IBM’s support team for further assistance.
Log each error message shown in the UI to a log file also. Error or warning messages shown to end users in the UI should also be logged in a file, so that these messages can be traced at a later time for diagnosis and recovery. The CBE infrastructure provides a logging facility for this purpose.
For error messages shown in the Console view or logged in files, show the message ID as the first item and make it a hyperlink to additional information. Error messages displayed in the Console view should continue to show the message ID as the first item, but it should be a hyperlink to additional information, so that users can diagnose a problem quickly.
For error messages shown in the Problems view, exploit the QuickFix feature to offer solutions to users. Since limited space is available in the Problems view, for errors or warnings shown in that view, we should exploit the QuickFix feature to offer solutions to users where possible.
Tips and Tricks
• When it is not feasible to consolidate, transform or coordinate every error bubbled up through the various sub-systems or dependent components, focus work effort on the errors frequently encountered in typical user scenarios.
• Obtain a list of top PMRs from our support team, and address those errors as a first priority.
• Leverage the symptom database, information developers and user experience designers to transform error text into meaningful and understandable descriptions for users.
• Use contextual information in the Eclipse IDE workbench, such as currently enabled capabilities, or current user role or persona (e.g. Java developer), to scope the error text.
Sample Error Messages in Our Products
Here are some sample error messages from IBM’s products, to illustrate the inconsistency among messages and the user’s challenge in understanding error conditions.
Here are the good examples
[ TBD - screen captures ]
For consistency and clarity in Properties, use the standard tabbed view with proper tab ordering, flexible layout, detailed user assistance, accurate multi-selection, and no sub-tabs.
Across many Eclipse-based products, the Properties view is being used and presented inconsistently. This inconsistency is problematic for users who use more than one of these products. Moreover, poor choices for layout, controls, and labeling can significantly reduce the effectiveness and efficiency of a Properties view.
Use the standard tabbed view for product consistency. (Figure 1 below shows an example.) Both tabs and a table of Properties should be supported – the tabs for novices, the table for experts. Ideally, the tabs and table will be toggled via toolbar control, for quick transitions. If there is no toggle and the table will be presented on the last tab instead, the best name for this tab is “All”. This is a descriptive and accurate name, and the tabular presentation will help to keep problematic items out of the hands of novices.
Tabs should be labeled in order: General, . . . , All. Every Properties view should feature a General tab, which contains the most frequently used properties. This will speed up new users as they get oriented. The last tab should be named All and contain a table view, if one is supported. The middle tabs? They should follow relevant concepts in other products, where possible, using similar names and organization. Otherwise, there are no specific recommendations for middle tabs.
Avoid using sub-tabs when possible. There are several reasons for this recommendation. First, sub-tabs are not easily discoverable by users, since the sub-tabs usually aren't visible unless a top-level tab is selected. Second, sub-tabs take longer to navigate to, even when a user is familiar with them. Finally, sub-tabs add a level of complexity that in most cases can be designed around, especially through the use of an “All” tab.
A Properties view must be accessible via a context menu for an object or editor. Allow users to detach or Fastview this view to support an open editor. Such support is needed to let users see a large diagram editor and properties at the same time. Detached views (via the view context menu) are supported in Eclipse 3.1 and beyond and can easily work for Properties. Such views have the advantage of persisting across opening and closing, but they have the disadvantage of always being on top (obscuring the editor). Another good option is to make a Fast View of Properties, so that it can be displayed on top as needed.
Tab layout should gracefully adapt to view orientation (horizontal or vertical). Depending on the other tools that a user works with, screen real estate may require opening a Properties view in either orientation. As needed, tab content should be laid out dynamically for re-orientation. It is reasonable to design a Properties view for a predominant orientation, depending on use case, but the less common orientation should be addressed as well.
Dynamic Help and tooltips can clarify fields and data. (Dynamic Help was introduced in Eclipse 3.1.) Simple properties can initially be confusing for novice users, and complex properties can occasionally be confusing even for expert users. Accordingly, use Dynamic Help when possible. Field-level Dynamic Help is desirable; otherwise, a backup approach is to provide hover help (tooltips).
Tips and Tricks
When multiple objects are selected in the editor, follow these guidelines.
• Display only those properties that are meaningful to the collection of objects. Any setting changes are applied to all the underlying objects
• Display the common properties of all the selected objects. Where the property values differ, display the controls associated with those values using a mixed state.
• If the selected object is a collection of multiple discrete objects (e.g., a file folder), display the properties of the single grouped object, instead of a multiple-object property sheet for the discrete objects.
Figure 1: A tabbed view with recommended control layout.
Limit Context Menus
Remove extra items from context menus on objects in editors and views.
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.
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.
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.
This issue is addressed in the Eclipse UI Guidelines 2.1, in the section titled “Component Development - Editors” (Guidelines 6.11-6.13).
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.
- Design provides guidance and tools for creating Eclipse style icons and wizard graphics.
- 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.
- 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.
This section provides guidance and tools for creating Eclipse style icons and wizard graphics.
- Style & Design covers style characteristics and gives guidance for designing effective Eclipse user interface graphics including topics such as metaphor, composition, lighting, color and more.
- 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.
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.
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.
<This will be a list of links for all resources in the guidelines document>
<Add link to browsable icon inventory once ready>
<Numbered guidelines to go here>