Naming and User Interface Conventions

7/28/2019 Naming and User Interface Conventions

1/117

Naming Conventions

From Eclipsepedia

Contents

1 General

o 1.1 Eclipse Workspace Projects

o 1.2 Java Packages

o 1.3 API Packages

o 1.4 Internal Implementation Packages

o 1.5 Test Suite Packages

o 1.6 Examples Packages

o 1.7 Additional rules 2 Classes and Interfaces

3 Methods

4 Variables

5 Constants

6 Plug-ins and Extension Points

7 System Files and Settings

General

Like other open source projects, the code base for the Eclipse project should avoid usingnames that reference a particular company or their commercial products.

Eclipse Workspace Projects

When Eclipse is being used to develop plug-ins for the Eclipse project, the name of theEclipse workspace project should match the name of the plug-in. For example,org.eclipse.core.runtime plug-in is developed in an Eclipse workspace project namedorg.eclipse.core.runtime.

Java Packages

The Eclipse Platform consists of a collection of Java packages. The package namespaceis managed in conformance with Sun's package naming guidelines; subpackages shouldnot be created without prior approval from the owner of the package subtree. Thepackages for the open-source Eclipse project are all subpackages org.eclipse.

The first package name segment after org.eclipse is generally the subproject name,followed by the component name.
http://wiki.eclipse.org/index.php/Naming_Conventions#General%23Generalhttp://wiki.eclipse.org/index.php/Naming_Conventions#Eclipse_Workspace_Projects%23Eclipse_Workspace_Projectshttp://wiki.eclipse.org/index.php/Naming_Conventions#Java_Packages%23Java_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#API_Packages%23API_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Internal_Implementation_Packages%23Internal_Implementation_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Test_Suite_Packages%23Test_Suite_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Examples_Packages%23Examples_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Additional_rules%23Additional_ruleshttp://wiki.eclipse.org/index.php/Naming_Conventions#Classes_and_Interfaces%23Classes_and_Interfaceshttp://wiki.eclipse.org/index.php/Naming_Conventions#Methods%23Methodshttp://wiki.eclipse.org/index.php/Naming_Conventions#Variables%23Variableshttp://wiki.eclipse.org/index.php/Naming_Conventions#Constants%23Constantshttp://wiki.eclipse.org/index.php/Naming_Conventions#Plug-ins_and_Extension_Points%23Plug-ins_and_Extension_Pointshttp://wiki.eclipse.org/index.php/Naming_Conventions#System_Files_and_Settings%23System_Files_and_Settingshttp://wiki.eclipse.org/index.php/Naming_Conventions#General%23Generalhttp://wiki.eclipse.org/index.php/Naming_Conventions#Eclipse_Workspace_Projects%23Eclipse_Workspace_Projectshttp://wiki.eclipse.org/index.php/Naming_Conventions#Java_Packages%23Java_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#API_Packages%23API_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Internal_Implementation_Packages%23Internal_Implementation_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Test_Suite_Packages%23Test_Suite_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Examples_Packages%23Examples_Packageshttp://wiki.eclipse.org/index.php/Naming_Conventions#Additional_rules%23Additional_ruleshttp://wiki.eclipse.org/index.php/Naming_Conventions#Classes_and_Interfaces%23Classes_and_Interfaceshttp://wiki.eclipse.org/index.php/Naming_Conventions#Methods%23Methodshttp://wiki.eclipse.org/index.php/Naming_Conventions#Variables%23Variableshttp://wiki.eclipse.org/index.php/Naming_Conventions#Constants%23Constantshttp://wiki.eclipse.org/index.php/Naming_Conventions#Plug-ins_and_Extension_Points%23Plug-ins_and_Extension_Pointshttp://wiki.eclipse.org/index.php/Naming_Conventions#System_Files_and_Settings%23System_Files_and_Settings


2/117

org.eclipse..[.*]- General form of packagenames

The following subprojects are assigned at the time of writing:

org.eclipse.jdt.[.*] - Java development tooling

org.eclipse.pde.[.*] - Plug-in development environment

The following package name segments are reserved:

internal - indicates an internal implementation package thatcontains no API

tests - indicates a non-API package that contains only test suitesexamples - indicates a non-API package that contains only examples

These name are used as qualifiers and appear between the subproject and componentname:

org.eclipse..internal.[.*] - internal packageorg.eclipse..tests.[.*] - testsorg.eclipse..examples.[.*] - examples

In the case of the Eclipse Platform proper, there is no subproject name, and the qualifiersappear immediately after the component name:

org.eclipse.[.*] - Eclipse Platform properorg.eclipse..internal[.*] - Eclipse Platform internal

packageorg.eclipse..tests[.*] - Eclipse Platform testsorg.eclipse..examples[.*] - Eclipse Platform examples

The following components of the Eclipse Platform proper are assigned at the time ofwriting:

org.eclipse.ant[.*] - Ant supportorg.eclipse.compare[.*] - Compare supportorg.eclipse.core[.*] - Platform coreorg.eclipse.debug[.*] - Debugorg.eclipse.help[.*] - Help supportorg.eclipse.jdi[.*] - Eclipse implementation of Java Debug Interface

(JDI)org.eclipse.jface[.*] - JFaceorg.eclipse.platform[.*] - Documentation

org.eclipse.scripting[.*] - Scripting supportorg.eclipse.sdk[.*] - SDK configurationorg.eclipse.search[.*] - Search supportorg.eclipse.swt[.*] - Standard Widget Toolkitorg.eclipse.ui[.*] - Workbenchorg.eclipse.update[.*] - Plug-in live updateorg.eclipse.vcm[.*] - Version and Configuration Managementorg.eclipse.webdav[.*] - WebDAV support


3/117

For example,

org.eclipse.jdt.internal.core.compiler - Correct usageorg.eclipse.jdt.core.internal.compiler - Incorrect. internal should

immediately follow subproject name.org.eclipse.core.internal.resources - Correct usage

org.eclipse.internal.core.resources - Incorrect. internal shouldnever immediately follow org.eclipse.

org.eclipse.core.resources.internal - Incorrect. internal shouldimmediately follow Eclipse Platform component name.

API Packages

API packages are ones that contain classes and interfaces that must be made available toISVs. The names of API packages need to make sense to the ISV. The number ofdifferent packages that the ISV needs to remember should be small, since a profusion ofAPI packages can make it difficult for ISVs to know which packages they need to import.Within an API package, all public classes and interfaces are considered API. The namesof API packages should not contain internal, tests, or examples to avoid confusion withthe scheme for naming non-API packages.

Internal Implementation Packages

All packages that are part of the platform implementation but contain no API that shouldbe exposed to ISVs are considered internal implementation packages. All implementationpackages should be flagged as internal, with the tag occurring just after the majorpackage name. ISVs will be told that all packages marked internal are out of bounds. (Asimple text search for ".internal." detects suspicious reference in source files; likewise,"/internal/" is suspicious in .class files).

Test Suite Packages

All packages containing test suites should be flagged as tests, with the tag occurring justafter the major package name. Fully automated tests are the norm; so, for example,org.eclipse.core.tests.resources would contain automated tests for API inorg.eclipse.core.resources. Interactive tests (ones requiring a hands-on tester) should beflagged with interactive as the last package name segment; so, for example,org.eclipse.core.tests.resources.interactive would contain the corresponding interactivetests.

Examples Packages

All packages containing examples that ship to ISVs should be flagged as examples, withthe tag occurring just after the major package name. For example,org.eclipse.swt.examples would contain examples for how to use the SWT API.

Additional rules


4/117

Package names should contain only lowercase ASCII alphanumerics, and avoid

underscore _ or dollar sign $ characters.

Classes and Interfaces

Sun's naming guidelines states

Class names should be nouns, in mixed case with the first letter of each internalword capitalized. Try to keep your class names simple and descriptive. Use wholewords - avoid acronyms and abbreviations (unless the abbreviation is much morewidely used than the long form, such as URL or HTML).

Examples:

class Raster;

class ImageSprite;

Interface names should be capitalized like class names.

For interface names, we follow the "I"-for-interface convention: all interface names areprefixed with an "I". For example, "IWorkspace" or "IIndex". This convention aids codereadability by making interface names more readily recognizable.

Additional rules:

The names of exception classes (subclasses of Exception) should follow thecommon practice of ending in "Exception".

Methods


Methods should be verbs, in mixed case with the first letter lowercase, with thefirst letter of each internal word capitalized.

Examples:

run();

runFast();

getBackground();

Additional rules:


5/117

The named of methods should follow common practice for naming getters(getX()), setters (setX()), and predicates (isX(), hasX()).

Variables


Except for variables, all instance, class, and class constants are in mixed case witha lowercase first letter. Internal words start with capital letters. Variable namesshould not start with underscore _ or dollar sign $ characters, even though bothare allowed.Variable names should be short yet meaningful. The choice of a variable nameshould be mnemonic - that is, designed to indicate to the casual observer theintent of its use. One-character variable names should be avoided except fortemporary "throwaway" variables. Common names for temporary variables are i,j, k, m, and n for integers; c, d, and e for characters.

Examples:

int i;

char c;

float myWidth;

Constants


The names of variables declared class constants and of ANSI constants should beall uppercase with words separated by underscores ("_").

Examples:

static final int MIN_WIDTH = 4;

static final int MAX_WIDTH = 999;

static final int GET_THE_CPU = 1;

Plug-ins and Extension Points

All plug-ins (and plug-in fragments), including the ones that are part of the EclipsePlatform, like the Resources and Workbench plug-ins, must have unique identifiersfollowing the same style of naming convention as Java packages. For example, theworkbench plug-in is named org.eclipse.ui.

The names of a plug-in and the names of the Java packages declared within the codelibrary of that plug-in commonly align. For example, the org.eclipse.ui plug-in declares


6/117

much of its code in packages named org.eclipse.ui.* . While alignment is therecommended practice, it is not an absolute requirement. For instance, the org.eclipse.uiplug-in also declares code in packages named org.eclipse.jface.*. The org.eclipse.ant.coreplug-in declares code in packages named org.eclipse.ant.core and org.apache.tools.ant.*.

The plug-in namespace is managed hierarchically; do not create plug-in without priorapproval from the owner of the enclosing namespace.

Extension points that expect multiple extensions should have plural names. For example,"builders" rather than "builder".

System Files and Settings

By convention, files or folders that start with a period ('.') are considered "system files"and should not be edited by users or, directly, by other components that do not "own"them.

Of special note is the ".settings" folder in a workspace project. This folder holds variousforms of preference or metadata specific to that workspace project. Files in this directorydo not have to start with a period (they are assumed "system files" as they are in a"system folder") but they must follow the same naming conventions outlined elsewherein this guide. That is, they must identify themselves with their Eclipse Project'snamespace (e.g. org.eclipse.jdt, org.eclipse.jst, etc). and they should be as specific aspossible to denote the package they come from, or the function they are serving. Forexample,

org.eclipse.jdt.core.prefs

org.eclipse.jst.common.project.facet.core.prefsorg.eclipse.wst.common.project.facet.core.xml

Two obvious exceptions to this convention are the .classpath and .project files, but ...that's just because they were the first, before the large community of Eclipse was grasped.Following these namespace guidelines will help avoid conflicts where two plugins orprojects could accidently pick the same name for a metadata file.


7/117

Eclipse User Interface Guidelines

(Version 2.1 - 3.x Working Draft)

Nick Edgar, Kevin Haaland, Jin Li and Kimberley Peter

Last Updated: February 2004

Note: Please use thediscussion page to add comments instead of embedding them in thisdocument.

Note: We have created a section for hosting the drafts of ongoing Eclipse v3.x UIguidelines (Best Practices) updates.

Go to Eclipse UI Best Practices v3.x updates (Last updated in June, 2006)

Notice

Your feedback can influence the ideas and guidelines described here. If you havesuggestions, please provide us with your feedback on theUI mailing list or on thediscussion page.

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 inparticular. The real value comes from tool plug-ins that "teach" Eclipse how to work withthings - Java files, Web content, graphics, video - almost anything you can imagine.Eclipse allows you to independently develop tools that integrate with other people's toolsso seamlessly, you won't know where one tool ends and another starts. The very notion ofa 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 consistencybetween the registered components within the platform. This document attempts toreconcile this problem, by defining standard user interface guidelines for the creation ofnew components. If these guidelines are adopted within your own tools, it will lead togreater consistency with the platform and other tools, and an easier learning curve foryour customers.
http://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelineshttp://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelineshttp://wiki.eclipse.org/index.php/UI_Best_Practices_v3.xmailto:[email protected]?subject=UI%20Guidelines%20v2.1%20Feedbackmailto:[email protected]?subject=UI%20Guidelines%20v2.1%20Feedbackhttp://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelineshttp://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelineshttp://wiki.eclipse.org/index.php/UI_Best_Practices_v3.xmailto:[email protected]?subject=UI%20Guidelines%20v2.1%20Feedbackhttp://wiki.eclipse.org/index.php/Talk:User_Interface_Guidelines


8/117

These guidelines are intended for use by designers and implementors of an Eclipse userinterface extension.

The Workbench

To start out, let's take a look at the Eclipse workbench user interface, and the variouscomponents 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 existwholly within the perspective and are not shared, but any opened content editors areshared across perspectives. If two or more perspectives have the same view opened, theyshare the same instance of the view although its layout may differ in the perspectives. For
http://wiki.eclipse.org/index.php/Image:Workbench_decomposed.gif


9/117

perspectives in different Workbench windows, neither editors nor views are shared. Aperspective is like a page within a book. It exists within a window along with any numberof other perspectives and, like a page within a book, only one perspective is visible at anytime.

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 andProject menu are typically context specific, based on the current active perspective, frontmost 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 Editmenu, you will find familiar commands like Cut, Copy, Paste, and Delete. Thesecommands are known as global commands, and target the active part. In other words, ifthe 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 commandssuch 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, andlaunching external tools such Ant scripts. In the Window menu, you will find the OpenPerspective submenu to open different perspectives to suit to needs of your developmenttasks. You will find perspective layout management menu items. You will also find theShow View submenu to add views to the current Workbench window. In addition, youwill find the Preferences menu item, which is used to modify the functional preferencesof 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 regularfiles within the Eclipse workspace. The workspace consists of one or more top levelprojects. Each project contains a collection of folders and files. These objects are knownas resources.

Getting Started

For most developers, an introduction to the platform can be overwhelming, and you mayask "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 userinterface layer. In the model layer of Eclipse, known as the Workspace, is a collection of


10/117

resources (projects, folders and files). The user interface, or the Workbench, defines thepresentation for those resources.

As a UI developer, you will also have a model and a presentation. If we assume that yourgoal 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 dataobject, which users interact with. In every case, this content is the primary focus ofattention and a reflection of the primary task. To illustrate this concept, let's look at somecommon examples.

To do Java programming, the primary task is to create, edit, and debug Java code. Theprimary focus is the Java code, so an editor is used to interact with that code. Thenavigator, outline, and properties view exist to support the primary task, but rarely holdyour 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 primaryfocus is a particular email message, so an editor is used to view or reply to an emailmessage. 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. Theprimary focus is a particular conversation, so an editor is used to carry on thatconversation. A view may be used to list people with whom you can initiate aconversation.

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 primaryfocus of attention, it deserves a primary position in the UI (as an editor), and cancontribute 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 maydecide to edit the page you are looking at. This causes a new editor to open. Views areused 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 localtoolbar and local menu bar.

Once you have added a view or editor, an interesting question arises. Where did thismodel come from? In Eclipse, most data is created using a creation wizard. You maywant to add a creation wizard too. And once an object exists, you may need a way to editthe 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.


11/117

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 UserExperience, Macintosh Human Interface Guidelines, and Java Look and Feel Guidelines.You should continue to consult those guidelines for basic UI design and implementationrecommendations.

It is expected that you already have a basic understanding of the Eclipse UI architectureand APIs, and the basic UI design principles: user in control, directness, consistency,forgiveness, feedback, aesthetics, and simplicity. If you do not currently have theprerequisite 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 asingle team or by a partnership of teams, or the user may assemble a set of plug-ins fromdiverse 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) inEclipse for guidance. In many cases, the workflow you imagine may already exist inEclipse. If so, adopt the platform's workflow and user interface conventions. This willlead to greater consistency with the platform and other plug-ins, and an easier learningcurve 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 inan integrated environment, where other tools adopt the platform conventions. You losethe 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
http://wiki.eclipse.org/index.php/User_Interface_Guidelines#Best_Practices%23Best_Practiceshttp://www.eclipse.org/newsgroups/index.htmlhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Best_Practices%23Best_Practiceshttp://www.eclipse.org/newsgroups/index.html


12/117

Follow the platform lead for user interface conventions.

If you decide to reuse the conventions of Eclipse, be careful not to misappropriate Eclipsespecific UI conventions. For instance, the active part in a workbench window is indicatedby 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 partactivation in the window.

Guideline 1.3

Be careful not to mix UI metaphors. It may blur the original concept, and your ownapplication.

Eclipse is an open source project. If you feel your ideas are generally useful, join theEclipse community, write a proposal, and work with the Eclipse community to makeEclipse 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 abetter platform for all.

Capitalization
http://www.eclipse.org/http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:BadHilight.gifhttp://www.eclipse.org/


13/117

Consistent capitalization of text within a plug-in leads to a more polished feel, andgreater perception of quality. Within a dialog or window, headline capitalization shouldbe 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, andgroup labels. For example, "Choose an option for the Java file" can be used as a grouplabel.

Guideline 1.5

Use Headline style capitalization for menus, tooltip and all titles, including those used forwindows, dialogs, tabs, column headings and push buttons. Capitalize the first and lastwords, and all nouns, pronouns, adjectives, verbs and adverbs. Do not include endingpunctuation.

Guideline 1.6

Use Sentence style capitalization for all control labels in a dialog or window, includingthose for check boxes, radio buttons, group labels, and simple text fields. Capitalize thefirst 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. Inreflection of the different languages and numeric formats in each, a localization strategyshould 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 resourcescan 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 ofthe error.

Please refer to Wizards section for guidelines on how to handle user input errors in awizard.

Please refer to Editorssection for guidelines on how to handle errors occur in an editor, .
http://wiki.eclipse.org/index.php/User_Interface_Guidelines#Best_Practices%23Best_Practiceshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Wizards%23Wizardshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Editors%23Editorshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Editors%23Editorshttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Best_Practices%23Best_Practiceshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Wizards%23Wizardshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Editors%23Editors


14/117

When an error occurs which requires either an explicit user input or immediate attentionfrom users, a modal dialog should be used to communicate the error to the user. Thisforces 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 attentionfrom users, communicate the occurrence with a modal dialog.

If a programming error occurs in the product, an error dialog should be used tocommunicate the occurrence to the user. The error should also be logged using theworkbench error logging facility. This gives the user an opportunity to restart theplatform, uninstall the corresponding feature, and contact their system administrator.

The plug-in should provide the following information in the detail area of the errordialog:

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.

Visual Design

Go to 3.x updates

All visual user interface elements created for Eclipse follow a common style called theEclipse visual style orEclipse style. In these guidelines you will find basic designinformation, as well as specifications for implementing Eclipse style icons and wizardgraphics in tools based on the Eclipse framework.

Following these guidelines will help ensure consistency of visual user interface elementsand their implementation across the Eclipse tools and plug-ins. Consistency of theseelements includes visual semantic, style, and implementation considerations. These topicsare covered in the following sections.

Consistency
http://wiki.eclipse.org/index.php/Visual_Design_3.x_updateshttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Visual_Design_3.x_updates


15/117

In the development of the Eclipse style icons, a visual language was formed to describe avariety of concepts in the user interface. These concepts are now represented by a largeselection of tiny visual signs that many have come to know through using Eclipse tools.

In order to ensure a consistent visual experience, understanding of concepts across the

tools, and minimize confusion for the user, we encourage you to re-use Eclipse stylegraphical elements whenever possible.

Icon Reuse

A great many icons have already been created in the Eclipse visual style so there is agood chance many of the icons or graphical elements you may need already exist. Asample of the core concepts is shown in the following table. Each of these elementscarries with it a specific meaning, so care should be taken when using them to ensure that

consistent meaning is maintained.

Guideline 2.1

Re-use the core visual concepts to maintain consistent representation and meaning acrossEclipse plug-ins.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Metaphor_concepts.gif


16/117

Icon Palettes

Various palettes used in creating Eclipse style icons. There are 3 different palettes used to

create the 3 different icon states, as follows:

256 Color Palette for the active or selected also referred to as "color" state

of all icon types 8 Color Grayscale Palette for the enabled state of perspective, view, toolbar,

toolbar wizard, and local toolbar icons 2 Color Grayscale Palette for the disabled state of toolbar, toolbar wizard, and

local toolbar icons

256 Color Palette

Eclipse style icons should be designed using a special 256 color palette that consists of 20standard colors and 236 custom colors, as shown below.

NOTE: Although the color palette shown is based on the standard windows .aco colorpalette that comes with Adobe Photoshop, these two palettes are NOT the same andONLY the shown color palette should be used when creating Eclipse style icons.

Guideline 2.2

Use the Eclipse 256 color palette for creating the active or selected state of all icon types.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:256palette.gif


17/117

8 Color Grayscale Palette

To create grayscale, enabled versions of your full color icons, you will need to useanother palette that consists of the 8 colors shown below:

Guideline 2.3

Use the Eclipse 8 color palette for creating the enabled state of perspective, view, toolbar,toolbar wizard, and local toolbar icons.

2 Color Grayscale Palette

To create grayscale, disabled versions of your full color and enabled icons, you will needto use a subset of the 8 color palette, that consists of the 2 colors shown below:

Guideline 2.4

Use the Eclipse 2 color palette for creating the disabled state of toolbar, toolbar wizard,and local toolbar icons.

Icon Types

The Eclipse style icons have been categorized into separate types so that each can beoptimized for its specific location within the user interface. Below is a breakdown ofthese types and where they are located.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Disabledcolors.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Enabledcolors.gif


18/117

A ProductThe Product icon represents the branding of the product, and is always located on the farleft of the window title bar before the perspective, document, and product name.

B Perspective and FastviewPerspective and fastview icons are found down the left side of the workbench. These

icons allow the user to quickly switch between different opened perspectives, or toinvoke different views that have been created as fastviews.

C ToolbarToolbar icons are found on the main toolbar across the top of the workbench. These iconsinvoke an command, either globally or within the editor.

D Toolbar WizardToolbar wizard icons are found on the main toolbar across the top of the workbench.They are easily recognized by their wand and sparkle. Selecting one of these icons willlaunch a wizard.

E ViewView icons are found on the left side of the titlebar of each view within the workbench.These icons indicate each views function.

F Local (View) ToolbarLocal toolbar icons are found to the right of the view icon on the titlebar of each viewwithin the workbench. These icons invoke an command on objects in that view only.
http://wiki.eclipse.org/index.php/Image:Icon_types.gif


19/117

Local toolbar icons are also found in all menus, including main, pull down, and contextmenus.

G Model ObjectModel Object icons are found in tree views, list views, and on Editor Tabs within the the

workbench (such as files, folders, projects and so on).

H Object OverlayObject overlay icons are also found in tree or list views. They are appended to the variouscorners of model object icons as signifiers of some sort of change.

Guideline 2.5

Use the appropriate icon type in the location it is designed for within the user interface.

Icon Size & Placement

With few exceptions, Eclipse style icons are designed within an area of 16 x 16 pixels.Within that area, a 15 x 15 pixel space is reserved for the image itself, leaving both avertical and horizontal line of empty pixels to allow for proper placement of the imagewithin the interface. Note the location of the empty pixels in the samples below. Theicons are cut with the specific placement shown to ensure alignment in the user interface.

The diagrams below show the proper sizing of the separate types of icons, and theirproper placement within the allotted screen space.

View Icons

Maximum 16 pixels wide x 16 pixels high, alwayscentered.Empty pixels must be on the left, and bottom.
http://wiki.eclipse.org/index.php/Image:View_realestate.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


20/117

Perspective Icons

Fastview Icons

Maximum 16 pixels wide x 16 pixels high, alwayscentered.

Empty pixels must be on the right, and bottom.

Toolbar Icons

Toolbar Wizard Icons

Local Toolbar Icons

Maximum 16 pixels wide x 16 pixels high, always

centered.Empty pixels should be on the left, and top.

Model Object Icons

Maximum 16 pixels wide x 15 pixels high, alwayscentered.Model Object icons must be no greater than 15 pixels

high.

Object Overlay Icons

Object Overlays are one of the exceptions to the 16 x 16pixel size.Maximum 7 pixels wide x 8 pixels high, always centered.

Icon should have a white outside keyline around it toseparate it from the icon it is being appended to.See the next section on Icon Positioning for using thekeyline on different types of Object Overlay icons.

Guideline 2.6

Follow the specific size specifications for each type of icon.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Overlay_realestate.gifhttp://wiki.eclipse.org/index.php/Image:View_realestate.gifhttp://wiki.eclipse.org/index.php/Image:Toolbar_realestate.gifhttp://wiki.eclipse.org/index.php/Image:Perspective_realestate.gif


21/117

Guideline 2.7

Cut the icons with the specific placement shown to ensure alignment in the user interface.

Icon Positioning

To follow from the specific size and placement of the different types of icons within theirallotted screen space, the following positioning guidelines will help with the alignment ofthese elements relative to one another, and will aid in creating a well organized andaesthetically integrated user interface. (All measurements are in pixels.)

Overview

1. Toolbar icons

(Includes Toolbar and Toolbar Wizard Icons)
http://wiki.eclipse.org/index.php/Image:Iconposition_main.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


22/117

Item Positioning and Spacing

A Toolbar 22 pixels high

B Between left margin and handle 4 pixels

C Between handle and first icon 7 pixels

C Between icon and top of toolbar 3 pixels

C Between icon and bottom of toolbar 3 pixels

C Between icon and twisty 7 pixels

D Between twisty and hard rule 7 pixels

E Between hard rule and icon 6 pixels

F Between icons 7 pixels

G Between icon and hard rule 10 pixels

H Between hard rule and handle 2 pixels

2. Titlebar icons

(Includes View and Local Toolbar Icons)
http://wiki.eclipse.org/index.php/Image:Toolbar_specs.gif


23/117


A Title bar 22 pixels high

B Between left margin and view icon 4 pixels

B Between view icon and text label 3 pixels

B Between title bar icons and top of title bar 3 pixels

B Between title bar icons and bottom of title bar 3 pixels

C Between local toolbar icons 7 pixels

D Between last local toolbar icon and closingwindow 'x'

7 pixels

E Between closing window 'x' and right margin 4 pixels

3. Perspective icons

(Includes Perspective and Fastview Icons)
http://wiki.eclipse.org/index.php/Image:Titlebar_specs.gif


24/117

Perspective Icons

Item Positioning andSpacing

A Perspective bar 27 pixels wide

B Between left margin andicon

5 pixels

B Between icon and rightmargin

6 pixels

B Between top ofperspective section andfirst icon

3 pixels

B Between icon and hardrule

6 pixels

C Between hard rule and

top of icon

6 pixels

D Vertically between icons 6 pixels

E Between icon and hardrule

6 pixels

Fastview Icons

Item Positioning andSpacing

D Vertically between icons(same as perspectiveicons)

6 pixels

E Between icon and hardrule

6 pixels

F Between left margin andicon

5 pixels

F Between top of fastviewsection and first icon

3 pixels

F Between icon and rightmargin

6 pixels

4. Tree View icons

(Model Object Icons)
http://wiki.eclipse.org/index.php/Image:Perspective_specs.gif


25/117


A Between +/- widget and left of window 4 pixels

A Between +/- widget and top of window 4 pixels

B Between top of window and first icon 0 pixels

B Vertically between icons 0 pixels

B Between horizontal treeview branch and icon 0 pixels

B Between icon and text label 3 pixels

C Text is nested within the text label 3 pixels each on left and top,2 pixels on right, 4 pixels onbottom (length varies)

Icon Overlays

As stated under Icon Size & Placement, all overlays are consistently the same size: 7 x 8pixels. An additional white border keyline is included on Project Nature and Java Overlaytypes to visually separate them from the underlying Model Object icon. The keylinelocation varies depending on the overlay's placement on the underlying icon.

Project Nature Overlay

The project nature overlays are displayed in the Navigator and the Package views. Theyare completely superimposed on the model object at the top right corner of the 16 x 16icon space.

Only a few project nature overlay icons have been created to prevent crowding in theinterface. Project nature overlays quickly identify the various types of projects that canbe contained in the Navigator and mirroring views.

The white keyline border is applied around the image to enhance legibility.
http://wiki.eclipse.org/index.php/Image:Treeview_specs.gif


26/117

Auxiliary Overlay

The auxiliary overlays are displayed in all tree views. This type of overlay is completelysuperimposed 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 auxiliaryoverlays are warning, error,failure, andsuccess.

Java Overlay

The Java overlays are displayed in the Outline, Hierarchy, and Package views. The Javaoverlays are appended to the model object icon, so they extend the 16x16 icon space.They are placed to the right of a model object icon, overlapping the 16x16 model objectspace 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 beenassigned. In designing Java overlays, it is important to make sure the base object icon cansupport the addition of overlays without compromising readability. Note that there aretwo Java overlays that always display at the bottom right corner 'C' position in thelayout shown below of the model object: synchronized (method) and run (class).
http://wiki.eclipse.org/index.php/Image:Run_co.gifhttp://wiki.eclipse.org/index.php/Image:Synch_co.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_auxiliary.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_projectnature_sample.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_projectnature.gif


27/117

Java overlays identify attributes of an object. Examples of Java overlays arestatic,final,abstract, andsynchronized.

Note: In the Hierarchy and Outline views, the Java overlays are appended to the right ofthe model object as shown, but in the Package view they are stacked over the modelobject.

Version Control Overlay

Version control overlays are displayed in the Navigator view and in the Structure View ofthe Merge Editor in CVS. When they are displayed in the Navigator view, the overlay iscompletely 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 16x16 space.They are placed to the right of a model object icon, overlapping the 16x16 model objectspace by 3 pixels. In CVS there is a maximum of 2 overlays on the right of the object.
http://wiki.eclipse.org/index.php/Image:Ovr_versioncontrol.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_java_sample1.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_java.gif


28/117

Version control overlays identify a transition-state of an object. Examples of CVSoverlays are incoming, outgoing, in conflict, added, deleted, and changed.

Guideline 2.8

Follow the positioning guidelines for the different types of icons for optimal alignment ofthese elements relative to one another.

Wizard Palette

The Wizard Palette section shows the the special blue 183 color palette you will need to

create your wizard graphics.Eclipse style wizard banner graphics should be designed using a special blue 183 colorpalette, as shown below.

Guideline 2.9

Use the Eclipse special blue 183 color palette for creating wizard graphics.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Wizban183.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_versioncontrol_cvs_samp.gifhttp://wiki.eclipse.org/index.php/Image:Ovr_versioncontrol_cvs.gif


29/117

Wizard Size & Placement

The Wizard Sizing section gives the sizing guidelines for creating wizard bannergraphics.All wizard banner graphics are designed to fit within a specified screen space that is 75

pixels wide x 58 pixels high, in the top, right corner of the wizard.

The actual size of each wizard banner graphic will vary depending on the elementsinvolved, but should not exceed 55 pixels wide x 45 pixels high.

Within the wizard banner space allocation, there is no firm rule for where to place thewizard banner graphic. Generally, the graphic is centered vertically, and off-center to theleft horizontally.

Guideline 2.10

Follow the specific size specifications for wizard graphics.

Guideline 2.11
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Wizbans.gifhttp://wiki.eclipse.org/index.php/Image:Wizban.gif


30/117

Cut the wizard graphics with the specific placement shown to ensure alignment in thewizard banner area.

Implementation Conventions

Eclipse provides a set of directory names and structure for storing and accessing userinterface graphics easily in any plug-in. This section describes the naming conventionsand directory path used in Eclipse. If followed, the predefined directory names and pathallow for the icon and wizard graphic files to be implemented directly into the plug-instructure without any need for modifications.

From icon request to delivery, the naming and structure is the same. If you use a differentuser interface directory name or more than one directory to store graphics than thatspecified at request time, notify your visual design contact of these changes so that they

can maintain a parallel system. Further, keeping the number of directories in which youstore your graphics to a minimum, will reduce unnecessary duplication of graphics andease resource management issues considerably.

Directory Names and Structure

Once your icons have been conceptualized, designed, approved and cut, they are storedusing the directory naming convention and structure described below.

1. The name of the first level directory refers to the Eclipse platform: Icons used inan Eclipse plug-in are called org.eclipse.pluginname.ui_0.0.0 . Wherepluginname is substituted with the name of the plug-in and_0.0.0 is substitutedwith the Eclipse version number, for example, org.eclipse.debug.ui_2.1.0

2. Each plug-in that manages user interface elements for a tool set contains a secondlevel directory called icons.

3. Within the icons directory, there are separate folders with names that indicate thestate, type and size of the icons, as follows:

1. Thefirst letter of the folder name indicates the icon state. The letterc for color, d for

disabled, and e for enabled.2. Thenext 3 to 6 letters signify the icon type: toolbar (tool), local toolbar (lcl), view orperspective (view), model object (obj), overlay (ovr), wizard banner (wizban).

3. Thelast two digits of the folder name indicate the size of the icons within. Usually itwill be 16 (to indicate the 16 pixel by 16 pixel size), but there might be others (for


31/117

example, 32 would indicate the 32 x 32 size) depending on the plug-inrequirements.

The following image shows a complete directory structure for a plug-in.

NOTE:

1. For many plug-ins, inside the icons directory, there is a folder called "full" whichthen contains these icon type folders. This full folder is being phased out of the icondirectory structure for new plug-ins. The structure shown above is therecommended icon directory structure.

2. Your plug-in may not require all types of icons shown in the sample. The sampleillustrates the complete set of icon types that you may need in your plug-in. Inaddition, there are sometimes exceptions to this list of types in plug-ins that have a

special type of icon that is not covered by this standard set. This is rare, however,and we encourage you to get to know the different types and their respective states,and use the structure as shown.

3. When an icon has multiple states, the file name is the same across each of theactive (color), enabled, and disabled state folders. Because of this organization,using the states provided is important, and will prevent you from having to renamethe states of your icons if all were stored in the same folder.

Guideline 2.12

Follow the predefined directory structure and naming convention.

Guideline 2.13

Keep the original directory names provided.

Guideline 2.14
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:Impready_folderstructure.gif


32/117

Minimize duplication of graphics within a plugin by keeping all graphics in one, or few,first level user interface directories.

Guideline 2.15

Use the active, enabled, and disabled states provided.

File Names

Establishing file names before the icons are designed will help ensure appropriatelydescriptive names for the concepts they represent, and may prevent misuse of icons forpurposes not intended and duplicate file names. If the names are well considered inadvance, you will appreciate being able to quickly make the distinction between icontypes and find concepts more readily, especially as the volume of your graphic resources

increases.

Suggestions for File Name Suffixes

File suffixes are useful for making the distinction between types of user interfaceelements. They can be used to denote the location or function of an icon or wizardgraphic. The following table shows how suffixes are being used for image file names inEclipse:

Filename

SuffixUsed for icons with the

following function or location:Icon Type and Location

*_wiz.gif invoke a wizard, or are graphicswithin a wizard

Wizard banner graphics: used in wizarddialog windows.Wizard icons: used on wizard toolbars.

*_exec invoke executable files Toolbar icons: used in cascading menus,and global toolbars.

*_edit are in an editor view Toolbar icons: used in cascading menus,and global toolbars.

*_nav are in a navigator view Toolbar icons: used in cascading menus,and global toolbars.Local toolbar icons: found on the far right

of the title area of a view.View and perspective icons: found in thetop, left corner of a view.

*_misc do no fit into any of the othercategories

Toolbar icons: used in cascading menus,and global toolbars.View and perspective icons: found in thetop, left corner of a view.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


33/117

*_tsk represent tasks that user can do Local toolbar icons: found on the far rightof the title area of a view.Overlay icons: placed on top of a modelobject icon to indicate a change incondition.

Object icons: used in the tree view, listview, and properties view.View and perspective icons: found in thetop, left corner of a view.

*_mode toggles the working mode of theview

Local toolbar icons: found on the far rightof the title area of a view.

*_menu are found in a menu Local toolbar icons: found on the far rightof the title area of a view.

*_ps are found in a property sheet Local toolbar icons: found on the far rightof the title area of a view.View and perspective icons: found in thetop, left corner of a view.

*_obj represent model objects Model object icons: used in the tree view,list view, and properties view.

*_pal are model object icons on objectpalettes

Model object icons: used on object palettes

*_co is for commands that engage thesystem, e.g. build command

Toolbar icons: used in cascading menus,and global toolbars.Local toolbar icons: found on the far rightof the title area of a view.

To aid you in choosing your file names, we offer the following guidelines:

Guideline 2.16

Abbreviate file name instead of using the full icon name, e.g. New Interface becomes"newint".

Guideline 2.17

Use lower case characters in your file names, e.g. DTD becomes "dtd".

Guideline 2.18

Use 10 characters or less in your file names if possible (underscores count as a character).
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


34/117

Guideline 2.19

Use a file name suffix that describes its location or function in the tool, e.g. newint_wiz.

Guideline 2.20

Use transparent *.gif format for all user interface icons and wizard graphics, unless thecontext requires a different file format.

Guideline 2.21

Keep the original file names provided.

Component DevelopmentCommands

A command, which is invoked by a user to carry out some specific functions, may appearas an item in a menu, or an item in a toolbar. In reflection of this, it has attributes for themenu or tool item label, tooltip, and image.

As a plug-in developer, you can contribute commands to the window menu bar andtoolbar, or to individual views and editors. Contribution to the window is performedusing an action set, a set of task oriented commands which the user can show or hide.

Contribution to a view or editor is performed using individual command.

Here is an illustration of the main areas of contribution.


35/117

In this section we'll look at general command guidelines. For information on window,view, or editor specific guidelines, see Windows,Views, and Editors.

Appearance

Each command must have a label, tool tip, and image. If the command appears in atoolbar, the command image will be displayed on all platforms. If the command appearsin a menu, the image will only be displayed on some platforms, such as Windows 2000.The label and tool tip should use Headline style capitalization, as defined in General UIGuidelines.

Each command must provide one full color image. This image will be displayed if themouse is placed over the command. It will also be used to generate the enabled, disabled,and pressed images which appear in normal command use. Commands which arecontributed in code also have the option to define explicit images for enabled, disabled,and roll over. This option can be used for greater control over image appearance.
http://wiki.eclipse.org/index.php/User_Interface_Guidelines#Windows%23Windowshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Windows%23Windowshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Views%23Viewshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Editors%23Editorshttp://wiki.eclipse.org/index.php/Image:ActionExamples.gifhttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Windows%23Windowshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Views%23Viewshttp://wiki.eclipse.org/index.php/User_Interface_Guidelines#Editors%23Editors


36/117

The following snapshot shows the valid use of Headline capitalization in a toolbar.

Guideline 3.1

Each command must have a label, tool tip, and full color image. The label and tool tipmust use Headline style capitalization.

The tool tips for a command should describe the behavior which occursif the command isinvoked, independent of the current state. For push buttons, the label should decribe theresult of users pushing the button. For toggle buttons, it should describe its effect whenthe item is toggled on, and the label should not change depending on the state of thebutton. In Eclipse version 2.1, it is recommended that the tool tip for a command uses thesame text as that for the command label. For instance, in the following snapshot thebehavior of the Show Type Hierarchy button is shown using one tool tips text.

Guideline 3.2

The command tooltip should describe the result of the command, not the current state ofthe command. Use the text same as that for the command label.

For consistency, any command which has a similar behavior to existing commands in theworkbench, should adopt the same terminology.

When creating a resource, the term "New" should be used in an command or wizard. Forinstance, "New File", "New Project" and "New Java Class". The term "Delete" should beused when deleting an existing resource.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GoodTooltips.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:TooltipCaps.gif


37/117

When creating an object inside a resource (e.g., a tag in an XML file; a method or field ina Java class), the term "Add" should be used; the user is adding something to an existingresource.

Guideline 3.3

Adopt the labeling terminology of the workbench for New, Delete and Add commands.

Enablement

An command should only be enabled if it can be completed successfully. If this is not thecase, the command should be disabled.

Guideline 3.4

An command should only be enabled if it can be completed successfully.

Command enablement should be quick to calculate. If it is too expensive to calculate theenablement of an command, the command should be optimistically enabled. If thecommand is invoked, it should calculate the real enablement, and show a dialog to theuser if it is not available.

Guideline 3.5

Command enablement should be quick. If command enablement cannot be quick, enablethe command optimistically and display an appropriate message if the command isinvoked, but cannot be completed.

Dialogs

A dialog is used for modal interaction with the user. It can be used to solicit information,or provide feedback.

Initialization

When a dialog first opens, the initial focus should be given to the first control whereinformation is required from the user. This control can be determined by the tab order ofcontrols until a control is found where information is required. If the dialog providessimple feedback, or requires simple confirmation from the user, the initial focus may alsobe assigned to the default button.

Guideline 4.1

When a dialog opens, set the initial focus to the first input control in the container. Ifthere are no input controls, the initial focus should be assigned to the default button.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


38/117

Multiple Item Selection

Slush Bucket widgets (also known as the Twin Box design) should flow from the left tothe right with the source objects on the left and selected files on the right.

Slush Buckets should also have the following control buttons, in this order, for movingobjects from the source the selected buckets.

Button Function

> Add whatever is selected on the left to the right

< Remove selected items from the right

>> Add all (whether they are selected or not)

, >,


39/117

Use a wizard for any task consisting of many steps, which must be completed in aspecific order.

Appearance

At the top of each wizard is a header, containing a banner graphic and a text area. Thebanner graphic contains an image representing the wizard task, and should be createdwith a white to blue, gray scale palette for consistency with other banners in Eclipse.These colors also avoid distracting the user from the important fields of the wizard. Thetext area is used to prompt the user for information which is absent, and display errormessages if information is invalid. The presence of the header, with banner graphic andtext area, creates a more polished feel, and greater perception of quality to the wizard.

At the bottom of each wizard, a Back, Next, Finish, and Cancel button should appear.

Guideline 5.2

Each wizard must contain a header with a banner graphic and a text area for userfeedback. It must also contain Back, Next, Finish, and Cancel buttons in the footer.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:WizardAppearance.gif


40/117

Initialization

When a wizard first opens, the focus should be placed in the first field requiringinformation (see Guidelines 3.1). The header should be used to prompt the user for thefirst piece of required information.

It is not appropriate to display an error message. At this point, the user hasn't doneanything yet.

Guideline 5.3

Start the wizard with a prompt, not an error message.

The initial state of the wizard should be derived from the context where it is opened. Forinstance, in the New File wizard, the current workbench selection is examined. If it pointsto a valid project or folder, the wizard will pre-populate the parent field with the parentproject or folder name, and put cursor focus in the next field requiring user input. If theuser's selection does not point to a valid parent project or folder, the wizard will not pre-populate the folder name. Instead, it will leave the field blank and put the cursor focus inthe field. When the user's selection is on a file, a wizard may also go through thesecalculations using the parent folder or project of the file.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:BadWizardInit.gifhttp://wiki.eclipse.org/index.php/Image:GoodWizardInit.gif


41/117

Guideline 5.4

Seed the fields within the wizard using the current workbench state.

Validation of Data

Information validation within a wizard should be done in tab order. If the first requiredfield is empty, an informative prompt should be shown in the text area, directing the userto fill in the field. If the first required field is in error, an error message should be shownin the text area. If the first required field is valid, check the next field, and so on. The text

area should not be used to display more than one prompt or error at a time.

If dialog information is absent or invalid, the Next or Finish buttons should be disableduntil the situation is resolved. When resolution occurs, and all of the information has beenprovided, the Next or Finish buttons may be enabled.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:WizardFieldPopulation.gif


42/117

Error messages should only be displayed when user input is invalid.

Guideline 5.5
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:WizardErrorMsgs2.gifhttp://wiki.eclipse.org/index.php/Image:WizardErrorMsgs.gif


43/117

Validate the wizard data in tab order. Display a prompt when information is absent, andan error when information is invalid.

Guideline 5.6

Only enable the Next / Finish buttons if all required information in the dialog is presentand valid.

The error messages in a wizard should be intended for the end user, not the developer.With this in mind, message IDs should never be presented as part of the error text in thewizard's header area.

Guideline 5.7

Remove all programming message ID's from wizard text.

Browse Buttons

An edit field and "Browse..." button combination should be used whenever an existingobject is referenced within a wizard. The edit field is used for direct input of the existingobject, and the Browse button is used to browse and select the object from a list of allpossible choices.

For instance, in the New Java Class wizard, a "Browse..." button is placed beside the"Super Class" edit field. If the browse button is pressed, a Browse Dialog will appear,and the user can select a super class. This pattern should be used whenever a link will beestablished between a new object and an old one. The "Browse..." button should belocated to the right of the edit field.

Guideline 5.8

Use a Browse Button whenever an existing object is referenced in a wizard.

In the Browse Dialog, invalid choices should not appear. When the dialog is closed, andfocus returns to the parent control, refresh the enablement state of controls within thedialog. In particular, refresh the enablement of Next, Finish, and OK buttons.

An example of valid and invalid filtering is shown in the following snapshot.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:WizardMsgs.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


44/117
http://wiki.eclipse.org/index.php/Image:FolderSelection.gif


45/117

Wizard Completion

The New Resource and Import Wizards commonly create new files, folders, and projectswithin the workbench. If a single file is created, the wizard should open the file in aneditor in the active page. If more than one file is created, open the most important, or

central file. This makes it easier to modify and save the file.

Have a readme.html file for every example project, and open that readme.htmlautomatically upon project creation. This will give users an immediate overview of theexample: what it does, prerequisites, limitations, steps to take, and so on.

Guideline 5.9

If a new file is created, open the file in an editor. If a group of files are created, open themost important, or central file in an editor. Open the readme.html file upon creation of anexample project.

If a new project is created, the wizard should change the active perspective within theworkbench to one which is appropriate for the new project type. In Eclipse v2.1, users areprompted to confirm the switch to the preferred perspective when creating a new project.To avoid loss of context, plug-ins should use this, and not automatically switch withoutprompting. If users want to switch automatically in the future, they can choose "Do notshow this message again" in the confirmation dialog.

Guideline 5.10

If a new project is created, prompt users and change the active perspective to suit the

project type.

In either case, where a file, folder, or project is created, the wizard should select andreveal the new object in the appropriate view. This provides concrete evidence to the userthat, yes, the new object was created and now exists.

Guideline 5.11

If a new object is created, select and reveal the new object in the appropriate view.

In many situations, the creation of a resource may involve the creation of a project or

folder to contain the resource. If the containing project or folder can be created fromwithin the wizard (with a very reasonable set of defaults), the wizard should allow it. Ifthe creation of such resources requires detailed user interaction in order for parent projector folder to be set up correctly, the wizard should not attempt to do this. Instead, thewizard error text should instruct the user that "The specified project does not exist".

The EAR Import wizard in IBM's WebSphere Studio is an example where allowing theuser to specify the name of the parent project in place makes for a much more usable


46/117

interaction. In this case, based on the user provided name, the wizard goes off and createsnot only the EAR project itself, but also any web projects, etc., that may be needed aswell.

Guideline 5.12

Create folder objects in a wizard if reasonable defaults can be defined.

Terminology

Within a creation wizard, if the item being created must be a Project (not a folder below aproject), the term "Project" should be used. If it can be a folder below the project, theterm "Folder" should be used. In addition, use the "name" suffix (uncapitalized) and noother prefix for the input field label. For example, use "Project name" or "Folder name"but not "Project Name" or "Server Project name".

Guideline 5.13

Use the term "Project name" for the input field label when the item must be a Project;otherwise, use the term "Folder name". Do not qualify the term.

Editors

An editor is a visual component within a workbench page. It is used to interact with theprimary content, which may be a document or data object. In every case, this content isthe primary focus of attention and a reflection of the primary task.

Guideline 6.1
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GoodParentCreation.gif


47/117

Use an editor to edit or browse a file, document, or other primary content.

Modifications made in an editor follow an open-save-close lifecycle model. When aneditor first opens, the editor contents should be unmodified (clean). If the contents aremodified, the editor should communicate this change to the platform. In response, an

asterisk will appear in the editor tab. The modifications should be buffered within the editmodel, until such a time as the user explicitly saves them. At that point, the modificationsshould be committed to the model storage.

Guideline 6.2

Modifications made in an editor must follow an open-save-close lifecycle model.

An editor is document or input-centric. Each editor has an input, and only one editor canexist for each editor input within a page. This policy has been designed to simplify partmanagement.

Guideline 6.3

Only one instance of an editor may exist, for each editor input, within a perspective.

In addition, it should be possible to open a separate instance of an editor for eachdifferent input.

Guideline 6.4

It must be possible to open a separate instance of an editor for each different input.

Appearance

The editor should be labeled with the name of the resource being edited; not with thename of the editor.

Guideline 6.5

The editor should be labeled with the name of the file, document, or input being edited.

If the editor contains more than one page, a tab control should be used for pageactivation. The use of this control is demonstrated by the plugin file and html editors.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:EditorTitles.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


48/117

Tab labels should be kept to one word, and two words at most.

Guideline 6.6

In multipage editors, use a tab control for page activation.Tab labels should be kept to

one word, and two words at most.

Menus

An editor may contribute items directly to the window menu bar. All of the commandsavailable in the editor should be displayed in the window menu bar, for accessibility andclarity. Exceptions are for the obvious commands, e.g. basic navigations such as next /previous character, line, word.

Guideline 6.7

All of the commands, except for the obvious commands, available in the editor should beadded to the window menu bar.

The following format is recommended, to ensure consistency across Eclipse and betterease of use.

Edit(one or more editorspecific menus)

Window

Add any object centriccommands here

(commands belong tothe specific menus)

Actions to control whatyou see in the editor.

Guideline 6.8

Use the standard format for editor contributions in the window menu bar.

The window menu bar contains a number of global commands, such as Cut, Copy, andPaste in the Edit menu. These commands target the active part, as indicated by a shadedtitle area. If these commands are supported within an editor, the editor should hook thesewindow commands, so that selection in the window menu bar or toolbar produces thesame result as selection of the same command in the editor. The editor should not ignorethese commands, and contribute duplicate commands to the window menu bar or toolbar.

A complete list of the global commands is declared in theIWorkbenchActionConstants.java (see below).

/*** From IWorkbenchActionConstants.* Standard global commands in a workbench window.*/


49/117

public static final String [] GLOBAL_ACTIONS = {UNDO,REDO,CUT,COPY,PASTE,PRINT,DELETE,FIND,SELECT_ALL,BOOKMARK};

Guideline 6.9

If an editor has support for Cut, Copy, Paste, or any of the global commands, thesecommands must be executable from the same commands in the window menu bar andtoolbar.

Toolbars

An editor may contribute commands directly to the window toolbar. The toolbar is usedto expose the most commonly usedcommands in an editor. Any command which appearsin the toolbar must also appear in the menu, but there is no need to duplicate everycommand in the menu within the toolbar.

Guideline 6.10

Fill the editor toolbar with the most commonly used items in the view menu.

The use of a local toolbar within an editor is contrary to the design of the workbench.Within the workbench, the toolbar for an editor is shared with editors of the same type.This reduces the flash which occurs when you switch between editors, reduces thenumber of images and commands in the product, and creates a better feel of integration.

Context Menus

A context menu should be used for context sensitive interaction with the objects in aneditor. If an object is selected in an editor, and the context menu is opened, the contextmenu should only contain commands which are appropriate for the selection. Commands

which affect the presentation of the view should not appear in the context menu.

In a text editor, you may assume that there is only one type of selection: text. In this case,the contents of the context menu will remain consistent for any selection in the editor.

Guideline 6.11

Fill the context menu with selection oriented commands.


50/117

For consistency with other editors in Eclipse, each editor should adopt a common orderfor commands within the context menu. This format is shown in the following table.Within this table, each item represents a category of commands. The categories withinthe context menu should be kept distinct from one another through the use of separators.

Undo / Redo

Add

Show In

Cut Copy Paste

Delete

Other Plugin Additions

Save

Guideline 6.12

Use the standard format for editor context menus.

For good spatial navigation, fill the context menu with a fixed set of commands for eachselection type. Once the contents have been defined, the enablement state of eachcommand should be determined using the selected object state. In doing so, you establisha consistency which makes the menu more predictable, and easier to navigate.

Guideline 6.13

Fill the context menu with a fixed set of commands for each selection type, and thenenable or disable each to reflect the selection state.

One of the primary goals for the platform UI is extensibility. In fact, it is this extensibilitywhich gives you the freedom to add new views, editors, perspectives, and actions to theplatform. Of course, extensibility is a two way street. While you may wish to extend theplatform, others may wish to extend your view or editor. It is common for one plug-in toadd actions to the menu, toolbar, or context menu of an editor from another plugin.

In the platform, the menu and toolbar for an editor are automatically extended by the

platform. In contrast, context menu extension is supported in collaboration between theeditor and the platform. To achieve this collaboration, an editor must register eachcontext menu it contains with the platform. It should also define an command filter foreach object type in the editor. An command filter makes it easier for one plug-in to addan command to objects in an editor defined by another plug-in. The target is describedusing object type and attributes. For more information on the implementation of thisconcept, refer to Creating an Eclipse View.
http://www.eclipse.org/articles/viewArticle/ViewArticle2.htmlhttp://www.eclipse.org/articles/viewArticle/ViewArticle2.htmlhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://www.eclipse.org/articles/viewArticle/ViewArticle2.html


51/117

Guideline 6.14

Register all context menus in the editor with the platform.

Guideline 6.15

Implement an Command Filter for each object type in the editor.

Resource Deletion

When a resource is deleted from one of the navigators (e.g., Navigator view, J2EE view,Data view, or DBA Explorer view in IBM's WebSphere Studio), the handling of anyeditor that is currently open on that resource depends on whether the editor has anyunsaved changes.

If the editor does not contain any changes since the resource was last saved then the

editor should be immediately closed.

Guideline 6.16

If the input to an editor is deleted, and the editor contains no changes, the editor shouldbe closed.

If the editor contains changes to the resource since the resource was last saved (i.e., it is"dirty"), the editor should give the user a chance to save their changes to another location,and then close. Here is a sample of the dialog which should be displayed:

Guideline 6.17

If the input to an editor is deleted, and the editor contains changes, the editor should give

the user a chance to save their changes to another location, and then close.

Unsaved Changes

If the editor contains changes to the resource since the resource was last saved (i.e., it is"dirty"), an asterisk should be used to prefix the resource name presented in the editortab:
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:FileDeletedDialog.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


52/117

Guideline 6.18

If the resource is dirty, prefix the resource name presented in the editor tab with anasterisk.

Read Only Files

With a name like "editor", it's not surprising that the issue of read-only files may cause

confusion. If it's read-only, how can you edit it? In this case, you should fall back to firstprinciples.

A view is typically used to navigate a hierarchy of information, open an editor, or displayproperties for the active editor. An editor is typically used to edit or browse a file,document or other input object.

This statement is appropriate whether a file is read-only or not. In either case, the usershould be able to select the file, open it, and browse the contents within an editor. If thefile is read-only, the File > Save command should be disabled and the File > Save Asshould be enabled. In the status bar area, "Read-only" should be shown instead of the

default "Writable" message.

Guideline 6.19

Treat read-only editor input as you would any other input. Enable the Save As if possible.Display "Read-only" in the status bar area.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:DirtyEditor.gif


53/117

Integration with Other Views

In Eclipse, there is a special relationship between each editor and the Outline view. Whenan editor is opened, the Outline view will connect to the editor, and ask it for an outlinemodel. If the editor answers an outline model, that model will be displayed in the Outline

view whenever the editor is active. The outline is used to navigate through the content, orinteract with the edit data at a higher level of abstraction.

For instance, if you open a .java file in an editor, the structure of the class is displayed inthe Outline view. If you select a method or field in the outline, the text declaration of thatitem will be selected and revealed in the editor. If you select a method or field, and openthe context menu, you can interact with the item as a conceptual unit, rather than just abunch of text.

In general, an editor should provide an outline model to the Outline view if the datawithin the editor is too extensive to see on a single screen, and will yield a structured

outline. This structured outline makes it very easy to navigate through objects like a javafile or html file.

Guideline 6.20

If the data within an editor is too extensive to see on a single screen, and will yield astructured outline, the editor should provide an outline model to the Outline view.

When an editor has an interaction with the Outline view, notification about locationshould be two-way. That is, the user should be able to select something in the outline and

have the editor position updated, and the user should be able to select something in theeditor pane and have the outline view updated.

A context menu should be available, as appropriate, in the outline view which shouldsupport creation operations as appropriate.

Guideline 6.21

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

If the edit model contains errors or warnings, they should be indicated in the Outlineview. An error or warning image should be added to the item with the error or warningrespectively. A container should have a red X if it there are errors on the container itself,a gray X if any of its descendents have errors (but not the container itself), and no X ifneither the container nor any of its descendents have errors. For instance, in the followingline, the addFastView method has an error, so an error image is added to the item and itsparent.
http://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gifhttp://wiki.eclipse.org/index.php/Image:GuidelineIndicator.gif


54/117

For this to work, care must be taken to design icons with overlay in mind, so that glyphscan be applied to the ancestor's icon.

Guideline 6.22

An error or warning image should be added to items with the error or warningrespectively. A container should have a red X if it there are errors on the container itself,a gray X if any of its descendents have errors

Documents

Naming and User Interface Conventions