Difference between revisions of "UI Best Practices v3.x"

From Eclipsepedia

Jump to: navigation, search
(Eclipse UI Best Practices v3.x Updates)
m (Guidelines: cat)
 
(48 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= Eclipse UI Best Practices v3.x Updates =
 
= Eclipse UI Best Practices v3.x Updates =
  
Last Updated: -- [[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 15:18, 27 January 2007 (EST)
+
These updates have been merged with the [[User Interface Guidelines|Eclipse 2.1 UI Guidelines]] document.
  
If you are looking for the Eclipse v2.1 UI guidelines, [[User Interface Guidelines|click here to return to Eclipse 2.1 UI Guidelines]]
 
  
To contribute ideas to expand these guidelines, please go to the Talk page: [[http://wiki.eclipse.org/index.php?title=Talk:User_Interface_Guidelines&redirect=no|User Interface Guidelines Talk Page]]
 
  
<br />
+
'''***THIS CONTENT WILL BE REMOVED ONCE THE MERGE IS COMPLETE***'''
This section 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.
+
  
=== <font color="#000000">Notice</font> ===
 
  
Your feedback can influence the ideas and best practices described here. If you have suggestions, please provide us with your feedback on the [mailto:platform-ui-dev@eclipse.org?subject=UI%20Best%20Practices%20v3.x%20Feedback  UI mailing list] or on the [http://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelines discussion page].
 
  
 +
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.
  
== Limit Context Menus ==
+
=== <font color="#000000">Notice</font> ===
  
=== Summary ===
+
Your feedback can influence the ideas and best practices described here. If you have suggestions, please provide us with your feedback on the [mailto:platform-ui-dev@eclipse.org?subject=UI%20Best%20Practices%20v3.x%20Feedback  UI mailing list] or on the [http://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelines discussion page].
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 ===
+
== Top Ten ==
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.
+
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.
  
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.
+
To see all considerations to-date go to the [[Top Ten Lists Working Page | Top Ten Lists Working Page]].
  
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).
+
==== 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"
  
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.
+
==== 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)
  
==== 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.
+
== General UI Guidelines ==
  
==== Good Examples ====
+
=== Common Error Messages ===
+
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.
+
'''Summary'''
+
Figure 3: a context-independent menu for the Outline View.
+
  
==== Related Information ====
+
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.
This issue is addressed in the Eclipse UI Guidelines 2.1, in the section titled “Component Development - Editors” (Guidelines 6.11-6.13).
+
  
<br />
 
  
== UI Graphics ==
+
'''Problem Description'''
'''''* In Progress *'''''
+
  
=== OVERVIEW ===
+
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.
  
'''Coverage'''
 
  
: 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 [http://www.eclipse.org 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.
+
'''Best Practice'''
  
: '''[[#DESIGN|DESIGN]]''' provides guidance and tools for creating Eclipse style icons and wizard graphics.
+
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.
  
: '''[[#SPECIFICATIONS|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|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'''
+
'''[ TODO: need more detailed info on the Eclipse v3.3 error message infrastructure...TBD ]'''
  
: 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.
 
  
 +
'''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:
  
=== DESIGN ===
+
• message ID <br>
This section provides guidance and tools for creating Eclipse style icons and wizard graphics.
+
• message text <br>
 +
• explanation <br>
 +
• action <br>
  
: '''[[UIGraphicsDesignStyle&Design|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.
+
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.
  
: '''[[UIGraphicsDesignConsistency&Reuse|Consistency & Reuse]]''' encourages consistency and reuse of existing graphical elements, and shows the core icon and wizard concepts currently in the tools.
 
  
: '''[[UIGraphicsDesignCommonElements|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.
+
'''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.
  
: '''[[UIGraphicsDesignStates|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.
 
  
: '''[[UIGraphicsDesignTemplates|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.
+
'''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.
  
  
=== Style & Design ===
+
'''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.
  
The Style &amp; Design section covers style characteristics and gives guidance for designing effective Eclipse user interface graphics including topics such as composition, lighting, color and more.
 
  
Before beginning to design Eclipse-style icons or wizard banner graphics, first check if the concept or visual elements have been covered already. Refer to the [[#Consistency&Reuse|Consistency & Reuse]] and [[#CommonElements|Common Elements]] sections for these elements. If designing an icon or wizard graphic from the start, consider the underlying concept and how it can best be represented. There might be an existing metaphor to appropriately convey the concept.
+
'''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.
  
==== Metaphor ====
 
The purpose of a metaphor is to create meaning. A metaphor will be meaningful if it is based on ideas the audience is already familiar with, and if it fits conceptually with the content and context. It should be clear, easily learned, and readily distinguishable. For example, project and file folders are used in the Eclipse-based workspace the same way they are used in the real world to organize and store project-related information. Since many concepts already have associated metaphors, use the existing metaphors, and when the concept allows, create new representations that extend the metaphor.
 
  
 +
'''Tips and Tricks'''
  
==== Icon style characteristics ====
+
• 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. <br>
The icons should have a clean elegant feel with rich but subtle color and lighting. They are rendered as if viewed directly from in front, but have the illusion of three dimensions. This affect is achieved by using color gradients and an implied light source from the top. A kind of ambient light is also used to illuminate different parts of each icon, either to bring out its shape or to emphasize a certain aspect of the image. Other key features include color gradient outlines to define edges and strong identifiable shapes with as few combined elements as possible.
+
• Obtain a list of top PMRs from our support team, and address those errors as a first priority. <br>
+
• Leverage the symptom database, information developers and user experience designers to transform error text into meaningful and understandable descriptions for users. <br>
+
• 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. <br>
'''Lighting'''
+
: For most elements, lighting is achieved with simple vertical gradients. The gradients go from a lighter color at the top of the element to a darker color at the bottom. This approach gives subtle form and illuminates basic elements such as files, folders, and other rectilinear shapes. For spheres, triangles and more complex forms, an additional reflective light source is added near the base of the element to give it volume and to ground it in its environment.
+
+
: [[Image:des_styl_char1.gif]]
+
+
: [[Image:des_styl_char2.gif]]
+
+
  
'''Outlines'''
 
: Each element within an individual icon features a single pixel keyline. Solid color lines define the top and bottom edges of the element, and gradients define the sides. To reinforce the light source from the top, the keyline color goes from light at the top to dark color at the bottom. The gradient along the sides bridges these light and dark colors.
 
  
: The color of the outline will vary according to the color of the individual element. In the example below, the file has a dark grayish-blue base and a light ochre color top. This is a standard color outline for this type of object. You will see that other elements use standard color outlines as well. Read more about standard colors under Color below, and use the [[#CommonElements|Common Elements]] design resource for reusable elements.
+
'''Good Examples'''
+
: [[Image:des_styl_char3.gif]]
+
  
+
'''Sample Error Messages in Our Products'''
'''Style differences between types'''
+
  
: '''''View''''' (includes Perspective and Fast View), '''''Model Object''''' (includes Table), '''''Object Overlay''''', '''''Progress Indicator''''', and '''''Diagram''''' icons have more saturated color and higher contrast than Toolbar, Local Toolbar, and Palette icons. It is important these icons stand out as focal points in the user interface because they are key indicators of the model. Since there are no tooltips associated with object type icons, they are less, or not, accessible to persons with low or no vision. Increased saturation and contrast helps compensate for this.
+
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.
+
: '''''Toolbar''''', '''''Toolbar Wizard''''', '''''Local Toolbar''''', and '''''Palette''''' icons have a more subtle approach to color and contrast than their object-based counterparts. These icons are more subtle because they are reliably present in the user interface and should not be distracting. Tooltips for these types of icons make them accessible to persons with low or no vision. Additionally, the use of color for the outlines, instead of black, means the images are not lost if people choose to work in a high-contrast (usually black) accessibility mode.
+
  
: A subset of core reusable elements illustrate this distinction best: Project, File, and Database elements each have a rich saturated version for the treeview and a light subtle version for the toolbar and local toolbar. Look for these differences in other icons within the [[#CommonElements|Common Elements]] files.
+
[[Image:error_msg1.jpg]]
+
: Here are the Project, File, and Database icons rendered as model objects:
+
: [[Image:des_styl_types_obj.gif]]
+
+
: Here are the same icons rendered in the more low-key toolbar style:
+
: [[Image:des_styl_types_tool.gif]]
+
  
 +
[[Image:error_msg2.jpg]]
  
==== Composition ====
+
[[Image:error_msg3.jpg]]
Aim for simplicity. Bring focus to the primary function or object within an icon by using different visual cues, such as color, contrast, lighting, size and location to differentiate elements. To improve clarity and reduce visual noise, avoid using too many elements within any given icon.
+
  
The location of individual elements in an icon can have an impact on its meaning and recognition value. People learn, recognize, and expect patterns: using a consistent location for visual elements, when possible, establishes a pattern that is useful for identifying the object type or function of an individual or set of icons.
 
 
'''Actions'''
 
: Actions in toolbar and local toolbar icons tend to be on the left of the icon and identify a command that will be performed on an object or set of objects. For example, the following icon represents "Deploy Script" on the toolbar. The action "deploy" is represented by a green arrow on the left of the script object:
 
 
: [[Image:des_styl_runscpt.gif]]
 
 
: However, not all actions are located on the left. To convey the intended meaning of a concept or to accommodate the context of the icon in the user interface, diverging from convention is sometimes required. Here are some actions that are notable exceptions to the action-on-the-left convention:
 
  
 +
'''Here are the good examples'''
  
: '''''Create''''' or '''''New''''' is represented by a sparkle in the upper-right corner to denote the creation of a sparkling "new" object. The sparkle, though an object itself, is a metaphor for creating something new. Its location in the icon space is precisely 1 pixel down from the top and flush with the right edge of the 16 x 16 icon space. Using this exact location ensures a clean uncluttered presentation when seen across a number of "new" action icons on the toolbar or in the menu. For example:
+
[ TBD - screen captures ]
  
: [[des_styl_create2.gif]]
 
 
: '''''Import''''', when associated with an object, is represented by an arrow in the bottom-right corner facing downward and to the right. Location and direction are important here to convey that an object will be imported from another location into the workbench. Note that its counterpart, '''''Export''''', follows the action-on-the-left convention with an arrow in the bottom-left corner because this location and direction is appropriate for denoting that an object will be exported from the workbench to another location.
 
  
: [[des_styl_export.gif]]
+
'''Related Information'''
+
: '''''Open''''' is represented by a curved arrow in the upper-right corner of the icon. The location, shape, and direction of the arrow indicate that the object is being opened. This action is used mostly on book- or file-type objects. For example:
+
  
: [[Image:des_styl_open.gif]]
+
TBD
+
: '''''Pin''''' is represented by a pushpin on the right of the object. The "Pin Fast View" icon is located on the right side of a view title bar. The location of the icon and the action within the icon indicate the side where the view will be pinned&mdash;on the right. Because of this location, the pin is pointing inward toward the object to be pinned. Placing the pin on the left would not work as well given the context and literal action of the icon.
+
  
: [[Image:des_styl_pin.gif]]
 
  
 +
== Component Development ==
 +
=== Properties View ===
  
'''Objects'''
+
'''Summary'''
: Objects are stacked vertically, often in large number, within treeviews and lists. Because of this stacking, attention to the alignment of objects within the icon design space is important. This is particularly true of repeated objects that use the same elements. For example, a file or folder used as a base for a series of model object images, should be located in the same place within the 16 x 16 pixel icon space in all of the images within the series. To illustrate the difference between aligned and not aligned objects, first, here is an example showing the base element&mdash;in this case the yellow folder&mdash;not aligned the same throughout a series of icons. The result is a choppy, harder to scan treeview or list:
+
  
: [[Image:des_styl_obj-unalign.gif]]
+
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.
+
: Second, here is an example showing the same base folder element aligned throughout the set. The result is a clean, easier to scan treeview or list:
+
+
: [[Image:des_styl_obj-align.gif]]
+
  
 
'''States'''
 
: States are the result of a direct of indirect action on an object. Once an action is taken on an object, the object reflects that action by showing its <em>state</em>. This state is generally shown on the right side of the icon. For example, invoking the action "Run on Server" will show the server running in the Servers view with a green arrow run action on the right side of the server object.
 
 
: [[Image:des_styl_state-start.gif]]
 
  
: Stopping the server will show the blue square stop action on the right of the server object.
+
'''Problem Description'''
+
: [[Image:des_styl_state-stop.gif]]
+
  
==== Color ====
+
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.
''' Summary '''
+
: Use a common color palette as the basis for creating graphical elements.
+
  
''' Problem Description'''
 
: An entire set of graphical elements, such as icons, wizards and user assistance graphics, requires a consistent, family-like appearance across the user interface (UI); contrarily, individual and sub-families of graphics require differentiation. Color choices can either bring unity or cause distraction.
 
  
: Eclipse supports 24 bit color depth, which means that colors used to create UI graphics can come from outside the defined 8 bit, or 256 color Eclipse-style palette. However, using the Eclipse-style palette as the base for applying color to your graphics will help ensure a visual fit within the Eclipse environment.
+
'''Best Practice'''
  
''' Best Practice '''
+
'''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.
: To achieve a consistent appearance in graphics across the UI, use a common color palette as the basis for creating your graphical elements.
+
  
: Eclipse-based graphics tend to use a common or dominant set of colors: Blue and yellow are the base colors, with green, red, brown, purple, and beige used for signifying specific object types or functions. Here is the palette, with a number of examples of how its different colors are used.
+
'''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.
  
: [[Image:des_colour_pal.jpg]]
+
'''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.
  
: '''''Figure 1.0'''''  The Eclipse-style palette contains the core and dominant colors used in Eclipse-based icons, wizard banner graphics, and user assistance graphics. Go to the Implementation section below to download this palette.
+
'''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.
  
: [[Image:des_styl_blueyellow.gif]]
+
'''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).
  
: '''''Figure 1.1'''''  The two dominant colors, blue and yellow, bring harmony to the overall presentation of the user interface. Themselves complementary, blue and yellow form a base on which to apply accent colors. These few examples show blue and yellow as the common base for different icons, and how other accent colors have been applied to help convey a concept.
 
  
: [[Image:des_styl_green.gif]]
+
'''Tips and Tricks'''
  
: '''''Figure 1.2'''''  Green is often used to indicate that something is being run or initiated, and as a common accent color. The actions "run" and "play" are prime examples of how the color green is applied to support a concept.
+
When multiple objects are selected in the editor, follow these guidelines.
  
: [[Image:des_styl_red.gif]]
+
• Display only those properties that are meaningful to the collection of objects. Any setting changes are applied to all the underlying objects <br>
 +
• 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. <br>
 +
• 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. <br>
  
: '''''Figure 1.3'''''  Red is used to indicate an error or to signal an alert, but red is also used in real-world objects that are typically red.
 
  
: [[Image:des_styl_brown.gif]]
+
'''Good Examples'''
  
: '''''Figure 1.4'''''  Brown is used less than the other colors mentioned, but it is generally associated with specific types of objects: the Java "package", "bundle", and the "Enterprise Java Bean (EJB)".
 
  
: [[Image:ddes_styl_purple-alt.gif]]
+
[[Image:PropertiesView_Figure1.jpg]]
  
: '''''Figure 1.5'''''  Purple is associated with “Web Site" or "Site Project", plugin "fragment", and Java "Interface”.
+
'''Figure 1: A tabbed view with recommended control layout.'''
  
: [[Image:ddes_styl_beige.gif]]
 
  
: '''''Figure 1.6'''''  Beige is associated with "template" and "generic" objects. While not limited to these two object types, beige is usually reserved for placeholder or unrealized objects.
+
'''Related Information'''
  
 +
TBD
  
''' Tips and Tricks '''
 
: '''1. Use color from existing graphics'''
 
: To quickly make graphics that are consistent with the Eclipse style without having to use the palette directly, select colors from existing Eclipse-based icons and wizards.
 
  
: '''2. Consider the background'''
 
: When designing an icon, keep in mind the background color it will sit on. The various browsers and operating systems allow custom window backgrounds that people can set according to their own preferences. It is not always possible to know if an icon will be used in different places in the user interface, but generally, the background will be either white or a warm or cool mid-tone grey. Whether it is white or grey will depend on the icon type. '''''Model Object''''', '''''Object Overlay''''', and '''''Diagram''''' icons are usually on a white background, whereas '''''Toolbar''''', '''''Toolbar Wizard''''', '''''Local Toolbar''''', and '''''Palette''''' icons usually sit on a mid-tone grey background.
 
 
: To achieve the best quality of color and edge treatment, test your icons across all known targeted operating system theme backgrounds. Modify the icons where needed to work well on most, if not all, of the backgrounds. Here is an example of testing a View icon with the different operating system theme selection colors, and a set of Toolbar icons on a number of known backgrounds:
 
 
: [[Image:des_bkgd_color.gif]]
 
  
: Antialiasing the edges is suitable if you know the background color. Since knowing the background color is not always possible, using medium to dark pixels on the edges will help ensure that the icon works well on most backgrounds. Using lighter edge pixels can result in poor quality, rough looking edges that do no blend well to the background. This is especially true of rounded shapes on dark backgrounds. The following example illustrates the effect of using lighter pixels on a round icon that sits on a medium to dark color background:
+
=== Limit Context Menus ===
+
: [[Image:des_styl_bg1.gif]]
+
+
: This example shows the same icon on the same background, but with darker edge pixels:
+
+
: In some special cases, a single icon may appear on multiple backgrounds and will need to be designed specifically for each case.
+
  
: '''3.  Download the palette'''  
+
'''Summary'''
  
: Click [[Media:eclipse-style_palette.zip | '''here''']] to download the "eclipse-style_palette.aco" palette for working with raster-based files in Adobe Photoshop, and the "eclipse-style_palette.ai" palette for working with vector-based files in Adobe Illustrator.
+
Remove extra items from context menus on objects in editors and views.
  
: If you are using The GIMP, click [[Media:eclipse-style_palette-png.zip | '''here''']] to download the “eclipse-style_palette.png” image file you will need to create a working palette.
 
  
: To load the palette in Adobe Photoshop, open the "Swatches" palette and choose "Load Swatches..."; then navigate to where you saved the "eclipse-style_palette.aco" palette.
+
'''Problem Description'''
  
: To load the palette in Adobe Illustrator, first save the "eclipse-style_palette.ai" palette in the Adobe Illustrator > Presets > Swatches folder. If you have Adobe Illustrator already open, you will need to restart it after adding this file. Once you restart Illustrator, go to Windows > Swatch Libraries and choose the "eclipse-style_palette.ai" palette from the list.  
+
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.  
  
: To create the palette in The GIMP, first open the “eclipse-style_palette.png” image, then add a New palette in Palette Dialog. In the Palette Editor, which opens automatically when you add a new palette, set the number of columns to “33” then, starting with the top row of the “eclipse-style_palette.png” image, select each color from left to right and click the New icon in the Palette Editor to add the color to the palette. Continue this for each row and Save the palette. It will then show in the list of palettes in the Palette Dialog.
 
  
: Save your images with the palette as a base
+
'''Best Practice'''
  
: In Adobe Photoshop, when an image is complete and ready to be saved to GIF, index the image to "exact" color. This indexing preserves all of the colors the graphic was created with, including any colors you have added that are not contained in the base palette.
+
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.
  
: In The GIMP, simply Save As GIF.
+
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).
  
'''Related Information'''
+
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.
: This is an update to the palette shown in Eclipse UI Guidelines 2.1, in the section titled “Visual Design – Icon Palettes” (Guidelines 2.2-2.4): http://www.eclipse.org/articles/Article-UI-Guidelines/Index.html
+
  
: The GIMP User Manual is available online at: http://www.gimp.org/docs/
 
 
  
=== Consistency & Reuse ===
+
'''Tips and Tricks'''
  
To come
+
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.
  
=== Common Elements ===
 
  
The Common Elements section 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 &amp; Reuse|Consistency &amp; Reuse]] section, this library will enable efficient creation of graphical elements and promote consistency throughout the user interface.
+
'''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.
  
'''Icon elements'''
 
  
: [[Image:des_common_icons.gif]]
+
'''Related Information'''
  
: Click [[Media:common_icon_elements.zip | '''here''']] to download the “common_icon_elements_eclipse-proj.psd” for Eclipse Project icons and the "common_icon_elements_eclipse-tools.psd" file for a subset of icons related to Eclipse-based tools.
+
This issue is addressed in the Eclipse UI Guidelines 2.1, in the section titled “Component Development - Editors” (Guidelines 6.11-6.13).
+
+
'''Wizard elements'''
+
  
: [[Image:des_common_wiz.gif]]
 
 
: Click [[Media:common_wizard_elements.zip | '''here''']] to download the "common_wizard_elements.ai" vector-based file for designing wizard banner graphics and the "common_wizard_elements.psd" raster-based file for cutting them.
 
  
 +
== UI Graphics ==
  
=== Icon States ===
+
=== Overview ===
The States section 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.
+
  
===== Enabled state =====
+
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 [http://www.eclipse.org 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.
: The enabled icon state is the color version of all toolbar, toolbar wizard, and local toolbar icons. This state indicates that a command is active and available for use. Information on creating the enabled color version of these icons can be found under '''[[#Style&Design|Style & Design]]''' above.
+
+
===== Disabled state =====
+
: The disabled icon state is a dimmed version of the enabled color toolbar, toolbar wizard, and local toolbar icons. This state indicates that a command is inactive and not available for use. The following image shows a set of disabled toolbar icons beside the enabled state. Note that the disabled versions are not strictly grayscale, they retain a hint of color from the original icon. This is achieved by adjusting the saturation and lightness as you will see in the automated action below:
+
+
: [[Image:des_states_enab-disab.gif]]
+
  
: '''NOTE:''' It is important to implement the graphical versions of the disabled state of toolbar and local toolbar icons. The quality and legibility of algorithmically rendered disabled icons is poor and they are not consistent with the majority of other tools that use the graphical versions.
 
  
 +
: '''[[#Design|Design]]''' provides guidance and tools for creating Eclipse style icons and wizard graphics.
  
: '''Creating the disabled icon state'''
+
: '''[[#Specifications|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.
: To create this state, you will use the "eclipse_disabledrender_R3V6.atn" action in the Eclipse-style Actions palette. Click [[Media:eclipse-style_actions.zip | '''here''']] to download the Eclipse-style Actions.
+
+
# Load the "eclipse_disabledrender_R3V6.atn" into the the Adobe Photoshop Actions palette.
+
# Use the marquee tool to select all the enabled versions of the toolbar and local toolbar icons you plan to create a disabled state for.
+
# Next, hold the control key and hit the left or right arrow key once, then let go of the control key and hit the opposite arrow key to bump the images back into their exact initial position.
+
# Start the "Create Disabled State" action by clicking on the "play" arrow at the bottom of the Actions palette. A copy of the color icons will be created and a series of changes will be made to the copies to make them look disabled. It happens quickly so if you want to deconstruct it, you will need to enable the dialog boxes to show while you run the action. These toggles on located on the left side of the Actions palette.
+
# Once the disabled state is made, there is usually some minor adjustments required. We recommend you go through each icon and tweak any pixels that don't look right and to give a consistent treatment to similar elements.
+
 
 
 +
: '''[[#Implementation|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.
  
: Here is what the "Create Disabled State" action looks like in the Actions palette:
 
 
: [[Image:des_states_disabled-atn.gif]]
 
  
===== Toggled states =====
+
: '''Audience'''
: The toggled state is used on toolbars, local toolbars, and in menus. On toolbars and local toolbars, a toggle is represented by a button with two physical positions&mdash;up and down&mdash;which define a state, most commonly &ldquo;on&rdquo; and &ldquo;off&rdquo;. Icons on a toggle button, like the tool tips that accompany them, should persist from one state to the next. The only thing that changes is the position of the button. For example:
+
+
: [[Image:des_states_toggles.gif]]
+
  
: Sometimes a toggle is not a simple on/off state. For example, there might be two different ways information can be displayed in a view. In this case, two buttons with two separate icons are required. The buttons sit beside one another on the local toolbar and when one is on, the other is off. For example:
+
: 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.
+
: [[Image:Listvshierarchy]]
+
: (Image not yet available: Toggle sample of two different ways of viewing something, e.g., list vs hierarchy)
+
+
===== Opened and closed folder states =====
+
: In the treeview, ideally, folders would be closed when the -/+ widget beside the folder icon is in a closed state, as in [+], and opened when the -/+ widget beside the folder icon is in an opened state, as in [-]. Because Eclipse does not animate opened and closed folder states in the treeview, project folders and regular folders are closed on the toolbar and local toolbar, but open in wizard banners and in treeviews. Here is the reasoning:
+
+
<ul>
+
: <li>On the toolbar, a closed folder represents one that has not been created yet.</li>
+
: <li>In a wizard banner, an open folder represents one that will be created in the form of a model object in the treeview.</li>
+
: <li>In the treeview, an open folder represents one an existing and active folder.</li>
+
</ul>
+
+
: One notable <strong>exception</strong> to open folders in the treeview is when used to represent a &ldquo;group&rdquo;, as is the case with high-level project groupings in the Project Explorer View. These are shown with closed folders.
+
  
: [[Image:des_states_folders.gif]]
 
 
  
'''NOTE:''' All instructions for creating visual elements are based on using Adobe Photoshop 7.0 and above and Adobe Illustrator 9.0 and above. If you use earlier versions of these tools, the instructions may not work exactly as described.
+
=== Design ===
 +
This section provides guidance and tools for creating Eclipse style icons and wizard graphics.
  
 +
: '''[[UI Graphics : Design : Style &amp; Design|Style &amp; Design]]''' covers style characteristics and gives guidance for designing effective Eclipse user interface graphics including topics such as metaphor, composition, lighting, color and more.
  
 +
: '''[[UI Graphics : Design : Consistency &amp; Reuse|Consistency &amp; Reuse]]''' encourages consistency and reuse of existing graphical elements, and shows the core icon and wizard concepts currently in the tools.
  
=== Design Templates ===
+
: '''[[UI Graphics : Design : Common Elements|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.
  
All design templates [[Media:eclipse3.0_UI_Design_resources.zip | '''here''']].
+
: '''[[UI Graphics : Design : States|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.
  
This section 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 also provided to help you get started quickly and working effectively.
+
: '''[[UI Graphics : Design : Templates|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.
  
Maintaining the simple structure of the templates will facilitate easy file sharing and efficient production of a large set of graphics for one tool.
+
=== Specifications ===
 +
This section details technical information you will need to design and prepare your Eclipse-style graphics for implementation.
  
====='''Icon Design Template'''=====
+
: '''[[UIGraphics : Specifications : FileFormats|File Formats]]''' lists and describes the graphic file formats used for the different graphic types.
  
# '''Populating the template''' : Fill out the [[Media:eclipse3.0_UI_Design_resources.zip | '''icon_design_template.psd''']] file with the names of all known required icons separated by type, for example view, toolbar, and model object. Feel free to add or remove rows as you need them. Each plug-in should have its own separate Photoshop document (PSD). If you have access to old icon files, these can be placed into the '''orig'''. (original) column as a reference or starting point.<p></p>
+
: '''[[UIGraphics : Specifications : GraphicTypes|Graphic Types]]''' describes the different types of graphics that are used in Eclipse-based tools, and where they are located within the user interface.
# '''Designing the icons''' : Before beginning to design Eclipse-style icons or wizard banner graphics, first check if the concept or visual elements have been covered already. See the [[#Consistency & Reuse|Consistency and Reuse]] and [[#Common Elements|Common Elements]] sections.<p> Create initial passes of your ideas, and then place them in the template. Up to five different concepts for any given icon can be placed in the version cells provided, i.e., columns '''A''', '''B''', '''C''', '''D''' and '''E'''. </p><p> When you are satisfied with the results, mark the icons you think are the strongest candidates with boxes on the '''preferred (black)''' layer, and send to the requester for feedback in the form of a flattened GIF image.</p>
+
# '''Revising the original concept''' : It is likely that revisions to the first pass will be required. If there is room, revised icons can be placed in the version cells next to the first pass ones. If you run out of cells or need to erase any previous icon concepts, but do not want to lose them forever, save a new version of the design file and make space for new ideas by removing the icons that are not likely to be used.<p> Once the icons have been approved, move the chosen images to the cut column. To ensure they are positioned properly within the allotted screen space, turn on the cut layer (pink) in the PSD. For guidance on size and placement of different types of icons, see the [[#Icon Size & Placement|Icon Size and Placement]] section.</p>
+
# '''Creating the disabled versions''' : See the [[#Icon States|Icon States]] section for instructions on creating the disabled state for Toolbar and Local Toolbar icons.<p></p>
+
# '''Cutting the icons''' : See the [[#Cutting Actions|Cutting Actions]] section for instructions on cutting the final images for delivery.<p></p>
+
# '''Marking revised icons''' :  It is likely that even after the icons have been cut and delivered to the developer, further revisions will be required or entirely new icons may be requested. To keep track of which icons and their instances need to be cut or re-cut, a red box can be placed around each, using the '''cut or re-cut (red)''' layer.
+
  
====='''Wizard Design Template'''=====
+
: '''[[UIGraphics : Specifications : IconSize&Placement|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.
  
# '''Populating the vector-based template''' : Fill out the vector-based template [[Media:eclipse3.0_UI_Design_resources.zip | vector-wizard_design_template.ai]] with the names of all required wizard banner graphics. As with the Icon Template, you can add or remove rows to suit the number of graphics you will be creating. If you have access to the related toolbar wizard icon file, add it to the file as a primary starting point. If you have access to old wizard graphics, these can be placed into the '''orig'''. (original) column as a secondary starting point.<p></p>
 
# '''Designing the wizard banner graphics''' : Before beginning to design Eclipse-style wizard banner graphics, first check if the toolbar icon that launches the wizard has been created already. This will provide the basis of your design. Also, check if any of the visual elements that will be part of the wizard graphic have been created already in Adobe Illustrator. See the [[#Consistency & Reuse|Consistency and Reuse]] and [[#Common Elements|Common Elements]] sections for existing elements.<p></p>The concept for a wizard banner should be closely aligned with, if not identical to, the toolbar wizard icon that launches the wizard dialog. Create an initial pass of each image on the '''New Wizard graphics''' layer, following the wizard banner stylistic treatment detailed in the [[#Style & Design|Style & Design]] section. As with the icons, more than one pass on the design may be required before coming to the final design.<p></p>When you are satisfied with the results, create a JPEG version of the template and send it to the requestor for feedback. Be sure to include the toolbar icon that corresponds to the wizard banner graphic as a reference.<p></p>
 
# '''Transferring vector-based images to the PSD template''' : Once the graphics are approved and ready to be cut, you will need to transfer them from the AI template to the PSD template. In the AI template, turn off all layers, except '''New Wizard graphics'''. <br>Select '''File > Save for Web''' from the menu. The settings you will need for this part of the transfer are shown here:<p></p><center>[[Image:des_temp_png_pref.gif]]</center><p></p>The PNG-24 file is temporary and is used to transfer high quality images from the AI file to the PSD file where you will use an action palette to cut the files.<p></p>
 
# '''Populating the PSD template''' : Fill out the [[Media:Eclipse3.0_UI_Design_resources.zip | eclipse_wizard_design_template.psd]] template with Layer Sets for each wizard banner graphic. Each Layer Set should have a single layer for the PNG-formatted wizard image. Add Layer Sets as you need them.<p></p>Open the temporary PNG file and transfer the wizard graphics, one per layer, to the corresponding Layer Set in the PSD file. Once all of your wizard graphics are transferred, Save the file. You are ready to cut.<p></p>
 
#  '''Cutting the wizard banner graphics''': See the [[#Cutting Actions|Cutting Actions]] section for instructions on cutting wizard banner graphics.<p></p>
 
  
 +
=== Implementation ===
 +
This section provides automated cutting actions, and conventions for file and folder naming and structure.
  
 +
: '''[[UIGraphicsImplementationCutting Actions|Cutting Actions]]''' describes the macros for cutting icons, icon overlays, and wizard banner graphics to get them ready for implementation.
  
=== SPECIFICATIONS ===
+
: '''[[UIGraphicsImplementationNamingConventions|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.
This section details technical information you will need to design and prepare your Eclipse-style graphics for implementation.
+
  
 +
: '''[[UIGraphicsImplementationFolderStructure|Folder Structure]]''' provides the Eclipse standard for folder names and structure for storing and implementing graphics within your plugin.
  
: '''[[UIGraphicsSpecificationsFileFormats|File Formats]]''' lists and describes the graphic file formats used for the different graphic types.
+
<br />
  
: '''[[UIGraphicsSpecificationsGraphicTypes|Graphic Types]]''' describes the different types of graphics that are used in Eclipse-based tools, and where they are located within the user interface.
+
== Resources ==
 +
<br /><This will be a list of links for all resources in the guidelines document>
  
: '''[[UIGraphicsSpecificationsIconSize&Placement|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.
+
<br /><Add link to browsable icon inventory once ready>
  
 +
<br />
  
 
+
== Guidelines ==
=== IMPLEMENTATION ===
+
<br /><Numbered guidelines to go here>
This section provides automated cutting actions, and conventions for file and folder naming and structure.
+
 
+
: '''[[UIGraphicsImplementationCutting Actions|Cutting Actions]]''' describes the macros for cutting icons, icon overlays, and wizard banner graphics to get them ready for implementation.
+
 
+
: '''[[UIGraphicsImplementationNamingConventions|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.
+
 
+
: '''[[UIGraphicsImplementationFolderStructure|Folder Structure]]''' provides the Eclipse standard for folder names and structure for storing and implementing graphics within your plugin.
+
  
  
Line 399: Line 281:
 
----
 
----
  
 +
[[Category:Best Practices]]
 +
[[Category:UI Guidelines]]
 
[[category: User Interface]]
 
[[category: User Interface]]

Latest revision as of 10:50, 11 May 2009

Contents

[edit] 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.

[edit] 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.


[edit] Top Ten

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.

[edit] Top Ten Eclipse UI Guidelines

  1. Use the Eclipse look and feel if extending or plugging into Eclipse
  2. Use common SWT controls to get what SWT offers for cross-platform adaptability and accessibility
  3. Be familiar with APIs for the UIs you are building
  4. Use icons and graphics consistent with the Eclipse style, decorations, states, and quality
  5. Understand the conventions of the OSs you are developing for
  6. Use understandable messages to help people recover from error conditions
  7. Don't initiate dialogs or wizards in an error state
  8. Use quick fix and quick assist mechanisms
  9. Reserve time for "polish"

[edit] Top Ten Eclipse UI Violations

  1. Low quality graphics or not consistent with the Eclipse style
  2. Poorly organized or sized dialogs and wizards
  3. Useless dialogs
  4. Cryptic error messages
  5. Messages with concatenated strings
  6. Property pages that don't adhere to platform uses (normal and tabbed)
  7. Assuming more importance than other contributions (see John/Mik comments below)


[edit] General UI Guidelines

[edit] Common Error Messages

Summary

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.


Problem Description

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.


Best Practice

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
• explanation
• action

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.


Good Examples

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.

Error msg1.jpg

Error msg2.jpg

Error msg3.jpg


Here are the good examples

[ TBD - screen captures ]


Related Information

TBD


[edit] Component Development

[edit] Properties View

Summary

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.


Problem Description

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.


Best Practice

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.


Good Examples


PropertiesView Figure1.jpg

Figure 1: A tabbed view with recommended control layout.


Related Information

TBD


[edit] 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).


[edit] UI Graphics

[edit] 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.


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.


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.


[edit] Design

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.

[edit] 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.


[edit] 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.


[edit] Resources


<This will be a list of links for all resources in the guidelines document>


<Add link to browsable icon inventory once ready>


[edit] Guidelines


<Numbered guidelines to go here>