User Interface Guidelines
From Eclipsepedia
Eclipse User Interface Guidelines (Version 2.1) with 3.x updates
This document is a working draft. Version 2.1 is the base with 3.x updates indicated with "(3.x update)".
Nick Edgar, Kevin Haaland, Jin Li and Kimberley Peter, with contributions from members of the User Interface Best Practices Working Group
Last Updated: November 2007
Note: Please use the discussion page to add comments instead of embedding them in this document.
Notice
Your feedback can influence the ideas and guidelines described here. If you have suggestions, please provide us with your feedback on the UI mailing list or on the discussion page.
UI Checklist
The UI Checklist is a shortlist of the most relevant and easy to apply Eclipse User Interface Guidelines. Start by using this list, referring to the linked guideline items for details, then use the Full Checklist for additional guidance. For comments please use bug 205326.
Introduction
In this document the Eclipse user interface guidelines are defined.
Eclipse is a universal tool platform - an open, extensible IDE for anything, but nothing in particular. The real value comes from tool plug-ins that "teach" Eclipse how to work with things - Java™ files, Web content, graphics, video - almost anything you can imagine. Eclipse allows you to independently develop tools that integrate with other people's tools so seamlessly, you won't know where one tool ends and another starts. The very notion of a tool, as we know it, disappears completely.
The platform is very flexible and extensible, but this flexibility has a serious drawback. In particular, there is no way within the program to ensure user interface consistency between the registered components within the platform. This document attempts to reconcile this problem, by defining standard user interface guidelines for the creation of new components. If these guidelines are adopted within your own tools, it will lead to greater consistency with the platform and other tools, and an easier learning curve for your customers.
These guidelines are intended for use by designers and implementors of an Eclipse user interface extension.
The Workbench
To start out, let's take a look at the Eclipse workbench user interface, and the various components within it.
The workbench is a collection of windows. Each window contains a menu bar, a toolbar, a shortcut bar and one or more perspectives.
A perspective is a visual container for a set of views and content editors. The views exist wholly within the perspective and are not shared, but any opened content editors are shared across perspectives. If two or more perspectives have the same view opened, they share the same instance of the view although its layout may differ in the perspectives. For perspectives in different Workbench windows, neither editors nor views are shared. A perspective is like a page within a book. It exists within a window along with any number of other perspectives and, like a page within a book, only one perspective is visible at any time.
The Workbench's main menu bar usually contains the File, Edit, Navigate, Project, Window, Help top-level menus. Other top-level menus that are in between the Edit and Project menu are typically context specific, based on the current active perspective, front most editor (whether active or not), and active view..
In the File menu you will find a New submenu, which contains menu items for Project, Folder, and File creation. The File menu also contains menu items for Import and Export, which are used to import files into the Workbench, and export them out again. In the Edit menu, you will find familiar commands like Cut, Copy, Paste, and Delete. These commands are known as global commands, and target the active part. In other words, if the Delete command is invoked with the Navigator active, the actual implementation is performed by the Navigator. In the Project menu, you will find project related commands such as Open project, Close project and Rebuild project are available. In the Run menu, you will find commands related to running and debugging application code, and launching external tools such Ant scripts. In the Window menu, you will find the Open Perspective submenu to open different perspectives to suit to needs of your development tasks. You will find perspective layout management menu items. You will also find the Show View submenu to add views to the current Workbench window. In addition, you will find the Preferences menu item, which is used to modify the functional preferences of the Workbench.
As a plug-in developer, you can contribute new views, editors, wizards, menu, and tool items to the platform. These contributions are defined using XML, and once registered, integrate seamlessly with the components which already exist in the platform.
Projects, Folders and Files
Eclipse can be used to create many different kinds of content - Java files, Web content, graphics, video - almost anything you can imagine. These objects are stored as regular files within the Eclipse workspace. The workspace consists of one or more top level projects. Each project contains a collection of folders and files. These objects are known as resources.
Getting Started
For most developers, an introduction to the platform can be overwhelming, and you may ask "where do I get started?". Here are a few basic guidelines which will help you.
This document is intended for UI designers and developers. With this audience in mind, we can talk about the two main layers of any application: the model layer and the user interface layer. In the model layer of Eclipse, known as the Workspace, is a collection of resources (projects, folders and files). The user interface, or the Workbench, defines the presentation for those resources.
As a UI developer, you will also have a model and a presentation. If we assume that your goal is to make the model visible, through some presentation, most developers will start out by adding a new view or editor to the workbench.
In Eclipse, an editor is used to contain the primary content, such as a document or data object, which users interact with. In every case, this content is the primary focus of attention and a reflection of the primary task. To illustrate this concept, let's look at some common examples.
To do Java programming, the primary task is to create, edit, and debug Java code. The primary focus is the Java code, so an editor is used to interact with that code. The navigator, outline, and properties view exist to support the primary task, but rarely hold your attention for an extended period of time while you are writing Java code.
To read email, the primary task is to create, send, read, and reply to email. The primary focus is a particular email message, so an editor is used to view or reply to an email message. A view may be used to select an email message to read, and open an editor.
To communicate using instant messaging, the primary task is the conversation. The primary focus is a particular conversation, so an editor is used to carry on that conversation. A view may be used to list people with whom you can initiate a conversation.
To browse the Web, the primary task is reading. The primary focus is a particular Web page, so an editor is used to browse the Web page.
In each case, the primary task determines the primary focus of attention. As the primary focus of attention, it deserves a primary position in the UI (as an editor), and can contribute commands to the workbench's main menu bar and toolbar.
A view may be used to save your favorite links, and reopen them. At any time, you may decide to edit the page you are looking at. This causes a new editor to open. Views are used to support the primary task. You use them to navigate a hierarchy of information, open an editor, or view properties for the active part. Each view may have its own local toolbar and local menu bar.
Once you have added a view or editor, an interesting question arises. Where did this model come from? In Eclipse, most data is created using a creation wizard. You may want to add a creation wizard too. And once an object exists, you may need a way to edit the properties for that object using a properties page, or the properties dialog.
All of these ideas will be discussed, in detail, in the following sections.
General UI Guidelines
This document defines UI guidelines that are unique and specific to the Eclipse platform. It is a supplement to the other standard UI guidelines such as Microsoft® User Experience, Macintosh Human Interface Guidelines, and Java Look and Feel Guidelines. You should continue to consult those guidelines for basic UI design and implementation recommendations.
It is expected that you already have a basic understanding of the Eclipse UI architecture and APIs, and the basic UI design principles: user in control, directness, consistency, forgiveness, feedback, aesthetics, and simplicity. If you do not currently have the prerequisite knowledge, please read the relevant documentation first.
Guideline 1.1
Follow and apply good user interface design principles: user in control, directness, consistency, forgiveness, feedback, aesthetics, and simplicity.
The Spirit of Eclipse
At its heart, Eclipse is a platform for tool plug-ins. These plug-ins may be developed by a single team or by a partnership of teams, or the user may assemble a set of plug-ins from diverse sources. In either case, the usability of an individual tool, and Eclipse as a whole, will be positively influenced by user interface consistency.
If you're in doubt about the appropriate look and feel for a tool, look to the platform first, then the Java development tooling and the Plug-in Development Environment (PDE) in Eclipse for guidance. In many cases, the workflow you imagine may already exist in Eclipse. If so, adopt the platform's workflow and user interface conventions. This will lead to greater consistency with the platform and other plug-ins, and an easier learning curve for your customers.
In some scenarios, it may be tempting to ignore the workflow of Eclipse and implement a "custom" user interface. This interface will almost certainly stand out like a sore thumb in an integrated environment, where other tools adopt the platform conventions. You lose the benefit of past experience, and force your customers to learn new ideas.
Consult the Best Practices section for examples and more information.
Also, visit the Eclipse platform newsgroups to share information with the community.
Guideline 1.2
Follow the platform lead for user interface conventions.
If you decide to reuse the conventions of Eclipse, be careful not to misappropriate Eclipse specific UI conventions. For instance, the active part in a workbench window is indicated by a shaded title. The use of shaded titles within an editor (see below) may be one way to indicate where the focus is, within that part, but it will also blur the concept of part activation in the window.
Guideline 1.3
Be careful not to mix UI metaphors. It may blur the original concept, and your own application.
Eclipse is an open source project. If you feel your ideas are generally useful, join the Eclipse community, write a proposal, and work with the Eclipse community to make Eclipse a better platform for product development and increase customer satisfaction.
Visit www.eclipse.org and join the Eclipse UI mailing list platform-ui-dev.
Guideline 1.4
If you have an interesting idea, work with the Eclipse community to make Eclipse a better platform for all.
Capitalization
Consistent capitalization of text within a plug-in leads to a more polished feel, and greater perception of quality. Within a dialog or window, headline capitalization should be applied to all titles, menus, tooltip, tabs, and push buttons. For example, "Run to Line" can be used as a menu item label.
Sentence style capitalization should be applied to all check boxes, radio buttons, and group labels. For example, "Choose an option for the Java file" can be used as a group label.
Guideline 1.5
Use Headline style capitalization for menus, tooltip and all titles, including those used for windows, dialogs, tabs, column headings and push buttons. Capitalize the first and last words, and all nouns, pronouns, adjectives, verbs and adverbs. Do not include ending punctuation.
Guideline 1.6
Use Sentence style capitalization for all control labels in a dialog or window, including those for check boxes, radio buttons, group labels, and simple text fields. Capitalize the first letter of the first word, and any proper names such as the word Java.
Language
Eclipse is available on a variety of different platforms, in a variety of locales. In reflection of the different languages and numeric formats in each, a localization strategy should be adopted for the text and images within each plug-in. This involves the separation of all resources from the source code of a plug-in itself, so that those resources can be translated to a new locale.
Consult the Best Practices section for examples and more information.
Guideline 1.7
Create localized version of the resources within your plug-in.
Error Handling
If an error occurs in Eclipse, the appropriate response will be dependent on the context of the error.
Please refer to Wizards section for guidelines on how to handle user input errors in a wizard.
Please refer to Editors section for guidelines on how to handle errors occurring in an editor.
When an error occurs which requires either an explicit user input or immediate attention from users, a modal dialog should be used to communicate the error to the user. This forces the user to notice, and deal with, the problem.
Guideline 1.8
When an error occurs which requires either an explicit user input or immediate attention from users, communicate the occurrence with a modal dialog.
If a programming error occurs in the product, an error dialog should be used to communicate the occurrence to the user. The error should also be logged using the workbench error logging facility. This gives the user an opportunity to restart the platform, uninstall the corresponding feature, and contact their system administrator.
The plug-in should provide the following information in the detail area of the error dialog:
- Provider name
- Plug-in name (user friendly name)
- Plug-in ID
- Version
Guideline 1.9
If a programming error occurs in the product, communicate the occurrence with a dialog, and log it.
UI Graphics (3.x updates)
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.
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.
Design
This section provides guidance and tools for creating Eclipse style icons and wizard graphics.
Style & Design
This section covers style characteristics and gives guidance for designing effective Eclipse user interface graphics including topics such as metaphor, 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 and 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.
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.
Icons
Style characteristics
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.
- 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.
- 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 Common Elements design resource for reusable elements.
- 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.
- 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 Common Elements files.
- Here are the Project, File, and Database icons rendered as model objects:
-
- Here are the same icons rendered in the more low-key toolbar style:
-
Composition
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:
- 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:
- 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:
- 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.
- 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:
- 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—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.
- Objects
- 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—in this case the yellow folder—not aligned the same throughout a series of icons. The result is a choppy, harder to scan treeview or list:
- 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:
- 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 state. 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.
- Stopping the server will show the blue square stop action on the right of the server object.
Color Palette & Themes
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.
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.
- The Eclipse-style palette contains the core and dominant colors used in Eclipse-based icons, wizard banner graphics, and user assistance graphics. Click here to download the "eclipse-style_palette.aco" palette, or go to the Implementation section to get more details about downloading the palette.
- 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.
- 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.
- 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.
- 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)".
- Purple is associated with “Web Site" or "Site Project", plugin "fragment", and Java "Interface”.
- 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.
- 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:
- 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:
- 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
- Click 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.
- If you are using The GIMP, click 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.
- 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.
- 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
- 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.
- In The GIMP, simply Save As GIF.
- Related Information
- This information replaces that provided in the 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/
Wizard Banner Graphics
Style characteristics
Like the Eclipse-style icons, wizard banner graphics have a clean presentation that is achieved by using rich but not overpowering color, a one-point perspective to show the elements clearly, subtle color gradients and soft lighting techniques to give the images a subtle three-dimensional form. Wizard banner graphics have the attribute of being larger than the icons, which allows for application of a more intricate, illustrative rendering style with more complex lighting.
- Lighting
- Lighting for the wizard banner graphics can be a simple unidirectional source or a complex multidimensional source, depending on the shape of the elements in the graphic. Unlike the icons, where the light source tends to come directly from above, the wizard graphics are lit mainly from the top left, have variable lighting that is tailored to each graphic, and have the added visual dimension of a cast shadow. The three-dimensional look is achieved by using color blends and gradients in Adobe Illustrator to render the highlights, mid-tones, shadows, and reflected light.
- Shadow
- For rectilinear objects, such as folders and files, an additional light source is implied from the left-front of the graphic, casting a shadow to the right of the graphic. This shadow is angled backward—to the right-back—at 45 degrees. When designing these types of graphics, consider the space the shadow will require by locating the graphical elements on the left side of the designated image area.
- Spherical objects have a different shadow treatment than their rectangular counterparts. The shadow is positioned directly below the object and is elliptical in shape. The sphere touches the shadow, which has the effect of grounding the sphere to the surface below. Use this type of shadow for spherical and flat-bottomed round objects, such as the "Java Method" sphere and "Service" bell, which are centered in the designated image area.
- Floating objects have a similar shadow to spherical objects in that the shadow is also elliptical in shape and positioned below the object. However, unlike the shadow for spherical objects, it does not touch the object. The object floats above the surface and casts a shadow directly below it. Use this type of shadow for elements that are centered and floating within the designated image area.
- Outlines
- Each element within an individual wizard graphic has a keyline to define its outer edges. Solid color lines define the top and bottom edges of the element. Gradients define the sides, going from a dark color at the bottom to a light color at the top. This approach applies to most common objects. However, there are many wizard graphics that are defined with flat color instead of gradients. Whether a gradient or flat color is used, choose an outline color that works well with the color of the element it defines. This is usually mid-tone color related to the dominant color used within the element. The following examples use established outline treatments and colors. Standard outline colors exist for many elements. To read more about the standard colors, see Color below, and use the Common Elements design resource for reusable elements.
- Here is an example of a gradient used to define the edges of a wizard graphic:
- Here is an example of a flat outline used to define the edges of a wizard graphic:
Composition
Composition of elements within wizard graphics follows most of the same practices described for icons. There are a few wizard-specific compositional concerns to be aware of for actions, objects, and states:
- Actions
- Actions in wizard banner graphics are generally shown in the same location as they are in the icon that launches them. A notable exception is the "create" sparkle, which is not shown at all in the wizard banner image. When in the toolbar wizard, the action is to create a specific kind of object. However, once in the wizard, the object is in the process of being created so the action is no longer necessary.
- Objects
- Objects, when overlapping, need to be clearly separated to ensure a legible image. The technique used in wizard banner graphics is to put a light glow around the front-most object.
- States
- States of objects, once in the wizard, change to what the state will be once the object is created. The most common example of this is the folder state: it is closed when in a toolbar wizard icon, but open when in a wizard banner graphic because it will be open once in a treeview or list view.
Color
Wizard graphic colors are based on the icons that launch them. The colors used to create a toolbar wizard icon, for instance, should be the same colors used to create its wizard banner counterpart. To download and use the color palette for creating wizard graphics, see the Color Palette & Themes section above under Icons.
As with the icons, wizard banner graphics fall under a limited set of color categories. These color categories are established for most elements and should be reused for like elements to maintain consistency, meaning, and identity. The following examples show how the different categories of color are applied to wizard banner graphics.
- Blue and yellow, as with the icons, are the two dominant colors and are used as a basis for many user interface graphics.
- Green, as with the icons, is often used to indicate that something is being run or initiated, and as a common accent color. The actions "run" and "play" are primary examples of how green is applied to support the concept.
- Red, as with the icons, is used to indicate an error or to signal an alert. It is also used for images that are typically red, such as a thermometer.
- Brown, as with the icons, is used to a lesser extent than the other colors noted, but it is generally associated with very specific types of objects. These objects are the Java "package", "bundle", and the "Enterprise Java Bean (EJB)".
- Purple, as with the icons, is associated with Java "Interface", plugin "fragment", and "Web Site" or "Site Project".
- Beige, as with the icons, is associated with "template" and "generic" objects. While not limited to these two object types, beige is usually reserved for placeholder or unrealized objects.
- Background color
- The background for wizard banners is part of the final graphic. It is a light blue curvilinear element that does not vary. However, the background color of the banner area does vary from one operation system and theme to another.
- Previous to Eclipse 3.3, all wizard banner graphics were in GIF format, which meant that the blue curvilinear element blended to a white background that was part of the final cut image. This worked well on standard Windows and OSX themes that have a white banner background, but not on Linux flavors that have a grey banner background. Fortunately, Eclipse now supports the PNG graphic format and all Eclipse Project (SDK) wizard banner graphics have been converted to PNG so that graphic blends to whatever background color it sits on.
Guideline 2.1 (3.x update)
Follow the visual style established for Eclipse UI graphics.
Guideline 2.2 (3.x update)
Use a common color palette as the basis for creating graphical elements.
Consistency & Reuse
This section encourages consistency and reuse of existing graphical elements, and shows the core icon and wizard concepts currently in the tools.
In the development of the Eclipse style graphical elements, a visual language was formed to describe a variety of concepts in the user interface. These concepts are now represented by a large selection of tiny visual signs that many have come to know through using Eclipse-based tools.
In order to ensure a consistent visual experience, a common understanding of concepts across the tools, and to minimize confusion, we encourage you to re-use Eclipse-style graphical elements whenever possible.
Re-using graphical elements
A great many icons and wizard graphics have already been created in the Eclipse visual style, so there is a good chance that the elements you might need already exist. Samples of existing core concepts for icons and wizard graphics are shown below. Each of these elements carries with it a specific meaning, so care should be taken when using them to ensure consistent meaning is maintained. A more extensive collection of common visual elements can be found on the Common Elements page.
Core icon concepts
Click here or on the image above to download the "core_icon_concepts.psd".
Core wizard graphic concepts
Click here or on the image above to download the "core_wizard_concepts.ai" and the "core_wizard_concepts.psd" files.
Guideline 2.3
Re-use the core visual concepts to maintain consistent representation and meaning across Eclipse plug-ins.
Common Elements
This 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 & Reuse section, this library will enable efficient creation of graphical elements and promote consistency throughout the user interface.
Icon elements
- Click 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.
Wizard elements
- Click 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.
Guideline 2.4
Re-use existing graphics from the Common Elements library or other Eclipse-based plugins.
States
This 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.
Icon States
This 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 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 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:
- NOTE: It is important to implement the graphical versions of the disabled state for 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.
- Creating the disabled icon state
- To create this state, you will use the "eclipse_disabledrender_R3V6.atn" action in the Eclipse-style Actions palette. Click 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.
- Here is what the "Create Disabled State" action looks like in the Actions palette:
- Toggled states
- 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—up and down—which define a state, most commonly “on” and “off”. 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:
- 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.
- 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:
-
- On the toolbar, a closed folder represents one that has not been created yet.
-
- In a wizard banner, an open folder represents one that will be created in the form of a model object in the treeview.
-
- In the treeview, an open folder represents one an existing and active folder.
- One notable exception to open folders in the treeview is when used to represent a “group”, as is the case with high-level project groupings in the Project Explorer View. These are shown with closed folders.
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.
Guideline 2.5
Create and implement the graphical versions of the disabled state for toolbar and local toolbar icons.
Templates
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 provided to help you get started quickly and working effectively.
All design templates here.
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.
Maintaining the simple structure of the templates will facilitate easy file sharing and efficient production of a large set of graphics for one tool.
Icon Design Template
- Populating the template : Fill out the 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.
- 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 and Reuse and Common Elements sections.
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.
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.
- 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.
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 and Placement section.
- Creating the disabled versions : See the States section for instructions on creating the disabled state for Toolbar and Local Toolbar icons.
- Cutting the icons : See the Cutting Actions section for instructions on cutting the final images for delivery.
- 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
- Populating the vector-based template : Fill out the vector-based template 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.
- 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 and Reuse and Common Elements sections for existing elements.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 section. As with the icons, more than one pass on the design may be required before coming to the final design.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.
- 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.
Select File > Save for Web from the menu. The settings you will need for this part of the transfer are shown here:
- Populating the PSD template : Fill out the 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.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.
- Cutting the wizard banner graphics: See the Cutting Actions section for instructions on cutting wizard banner graphics.
Guideline 2.6
Use the design templates for creating and maintaining UI graphics to facilitate easy file sharing and efficient production of a large set of graphics.
Specifications
This section details technical information you will need to design and prepare your Eclipse-style graphics for implementation.
File Formats
This section lists and describes the graphic file formats used for the different graphic types.
GIF - Graphics Interchange Format
GIF is the most common file format used in Eclipse-based tools. GIF images are raster-based, can have transparency, and tend to use a small amount of memory and disk space. Each GIF file contains a color palette of up to 256 individual colors. This format is most suited to images that use flat colors or have a limited number of colors. It is not a suitable format for photographic images.
The lossless compression method used in the GIF format suggests that the compressed image is identical to original image. However, because GIF is not capable of full color, images than contain greater than 256 colors will loose some of the original color through dithering, which creates the illusion of greater color depth by approximating the original colors used. Because of their physical size, 16 x 16 pixel icons can only accommodate 256 individual colors, so dithering is never a concern. However, it is something to be aware of when creating larger images.
GIF is used for the following types of graphics in Eclipse-based tooling:
- Product
- View (includes Perspective and Fast View)
- Toolbar (includes Toolbar Wizard)
- Local Toolbar
- Model Object
- Object Overlay (includes Underlay)
- Wizard Banner (some not yet converted to PNG)
- Table
- Palette
- Diagram (exceptions noted below under SVG)
- Progress Indicator
- Miscellaneous (there might be exceptions)
PNG - Portable Network Graphics
PNG is a bitmapped image format that employs lossless data compression. PNG was created to improve upon and replace the GIF format, as an image-file format not requiring a patent license. PNG is pronounced "ping" (/pɪŋ/ in IPA), but can be spoken "P-N-G" (as described at http://en.wikipedia.org/wiki/PNG). One of the great values of PNG format is it's support for alphas or transparency, allowing bleed through of the background on which these graphics sit.
PNG is used for the following types of graphics in Eclipse-based tooling:
- Wizard Banner
SVG - Scalable Vector Graphics format
SVG is a language for describing both two-dimensional and animated vector-based graphics in XML. One of its distinguishing attributes is its scalability: One size of an image will scale nicely to unlimited sizes. While there is great potential in using SVG for user interface graphics, especially on palettes and in diagrams, it currently has limited use in the tooling.
SVG is used for the following types of graphics in Eclipse-based tooling:
- Diagram (Action Bar only)
In designing graphics for SVG output, use a minimal number of elements in each image, especially for small 16 x 16 icons. This will help ensure image clarity, and fewer elements will keep the file size small.
BMP - Bit map format
BMP is the standard Microsoft Windows raster image format.
BMP is used for the following types of graphics in Eclipse-based tooling:
- Pointer
- Cursor
ICO - Icon format
ICO format is used on the Microsoft Windows operating system and is required for product install and launch icons, including desktop, treeview, and menu icons.
ICO is used for the following type of graphics in Eclipse-based tooling:
- Product icons (Windows)
ICNS - Mac Icon format
- Product icons (Mac)
XPM - X PixMap format
XPM is an ASCII image format that supports transparent color. This image format is used on Linux and is required for product install and launch icons, including desktop, treeview, and menu icons.
XPM is used for the following type of graphics in Eclipse-based tooling:
- Product icons (Linux)
Resources
- Mac
- Windows and Mac
Guideline 2.7
Use the file format specified for the graphic type.
Graphic Types
This section describes the different types of graphics that are used in Eclipse-based tools, and where they are located within the user interface.
The Eclipse style graphics have been categorized into separate types so that each can be optimized for its specific location. The majority of interface graphics are 16 x 16 pixels in size, though there are some graphic types that come in additional or unconventional sizes suited specifically to their use. Details on size and placement of the image see the next subsection on Icon Size & Placement. The following graphic types are described below:
Product
- The Product icon, also known as the Application icon, represents the branding of the product and is always located on the far left of the window title bar before the perspective, document, and product name. These icons are also used to launch the product from the menu or from a desktop or treeview shortcut, and as product identifiers in the About screen. Since these icons are intended for use in specific places, they are not meant for use on toolbars or in the user interface in general.
Perspective
- Perspective icons represent different working environments called "Perspectives". Each perspective is a set of views and content editors with a layout conducive to the tasks associated with that environment. The perspective icons allow the user to quickly switch between different opened perspectives. By default, these icons are located in the top right of the user interface to the right of the main toolbar, and have a horizontal orientation. They can also be docked on the top left just below the toolbar, keeping a horizontal orientation, or on the left of the navigator view with a vertical orientation.
- Type: View
- Folder name: view16
- Size: 16 x 16 pixels
- Format: GIF
Fast View
- Fast View icons allow users to quickly display different views that have been created as fast views. These icons are by default located in the bottom left of the user interface and have a horizontal orientation. They can also be docked with a vertical orientation on the left of the navigator view, or on the far right of the user interface.
- Type: View
- Folder name: view16
- Size: 16 x 16 pixels
- Format: GIF
Toolbar
- Toolbar icons are located on the main toolbar across the top of the workbench. They represent actions, and will invoke a command, either globally or within the editor.
- Type: Toolbar
- Folder names: etool16 and dtool16
- Size: 16 x 16 pixels
- Format: GIF
Toolbar Wizard
- Toolbar wizard icons are found on the main toolbar across the top of the workbench as well as in the New wizard dialog list. Selecting one of these icons will launch a wizard. The most common type of toolbar wizard is for creating "new" objects or resources. These are easily recognized by their gold sparkle in the upper right corner of the icon. The other common type of toolbar wizard is for generating files. These icons are distinguished by two stacked files in front of a diskette.
- Type: Toolbar
- Folder names: etool16 and dtool16
- Size: 16 x 16 pixels
- Format: GIF
View
- View icons are found on the left side of the titlebar of each view within the workbench. These icons indicate each view’s function or the type of object a view contains.
- Type: View
- Folder name: view16
- Size: 16 x 16 pixels
- Format: GIF
Local Toolbar
- Local toolbar icons are found to the right of the view icon on the titlebar of each view within the workbench. They represent actions, and invoke commands on objects in that view only. Local toolbar type icons are also used in all menus, including main, pull down, and context menus.
- Type: Local Toolbar
- Folder names: elcl16 and dlcl16
- Size: 16 x 16 pixels
- Format: GIF
Model Object
- Model Object icons are found in tree views, list views, and on editor tabs within the workbench. They represent objects and sometimes states, but not actions. Examples of model object icons are project folders and file types. Note that objects selected in the navigator view, such as the Package Explorer in the Java Perspective, have a one-to-one relationship with the file open in the Editor View, i.e., the same icon is used in both the navigator view and the Editor tab. In contrast, in the Outline View, the model object selected is not shown in the Editor, but the selection itself is shown in both the Outline View and the source code within the Editor.
- One-to-one relationship between model object in treeview and icon in Editor tab
- Model object in Outline View is not shown in the Editor, but the selection is shown in both views
- Type: Model Object
- Folder name: obj16
- Size: 16 x 16 pixels
- Format: GIF
Object Overlay (and Underlay)
- Object overlay icons are decorator elements that are used in tree or list views. They are appended to model object icons as signifiers of an object type, status, attribute, transition state, multiplicity or some sort of change. Underlays are a special type of underlay that go under the model object. Like the overlay, they signify some kind of change about the model object they append to.
- There are six main types of overlays:
- 1. Project Nature or Type
- These overlays are displayed in the Navigator and the Package views. They are completely superimposed on the model object at the top right corner of the 16 x 16 icon space.
- Only a few project nature overlay icons have been created to prevent crowding in the interface. Project nature overlays quickly identify the various types of projects that can be contained in the Navigator and mirroring views.
- The white keyline border is applied around the image to enhance legibility.
- Example:
- Type: Object Overlay
- Folder name: ovr16
- Size: 7 x 8 pixels
- Format: GIF
- 2. Auxiliary or Status
- These overlays are displayed in all tree views. This type of overlay is completely superimposed on the model object at the bottom left corner of the 16 x 16 icon space.
- The auxiliary overlay quickly identifies the status of an object. Examples of auxiliary overlays are warning, error, failure, and success.
- Example:
- Type: Object Overlay
- Folder name: ovr16
- Size: 7 x 8 pixels
- Format: GIF
- 3. Java or Attribute
- These overlays are displayed in the Outline, Hierarchy, and Package views. The Java overlays are appended to the model object icon, so they extend the 16 x 16 icon space. They are placed to the right of a model object icon, overlapping the 16 x 16 model object space by 3 pixels. A maximum of 3 java overlays can be put on the model object.
- The order in which an overlay appears depends on the order in which it has been assigned. In designing Java overlays, it is important to make sure the base object icon can support the addition of overlays without compromising readability. Note that there are two Java overlays that always display at the bottom right corner of the model object: Synchronize overlay synchronized (method) and Run overlay run (class).
- Java overlays identify attributes of an object. Examples include static, final, abstract, and synchronized.
- Note: In the Hierarchy and Outline views, the Java overlays are appended to the right of the model object as shown in the first example below, but in the Package view they are stacked over the model object, as shown in the second example.
- Examples:
- Hierarchy and Outline Views:
- Package View:
- Type: Object Overlay
- Folder name: ovr16
- Size: 7 x 8 pixels
- Format: GIF
- 4. Version Control or Transition-state
- These overlays are displayed in the Navigator view and in the Structure View of the Merge Editor in CVS. When they are displayed in the Navigator view, the overlay is completely superimposed on the model object at the right of the 16 x 16 icon space.
- When the version control overlays are displayed in the Structure View of the Merge Editor in CVS, they are appended to the model object, so they extend the 16 x 16 space. They are placed to the right of a model object icon, overlapping the 16 x 16 model object space by 3 pixels. In CVS there is a maximum of 2 overlays on the right of the object.
- Version control overlays identify a transition state of an object. Examples of these overlays are incoming, outgoing, in conflict, added, deleted, and changed.
- Examples:
