Eclipse UI Guidelines (v4-DRAFT)

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

This section 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.

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.

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.

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.

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.

Download all design 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 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.

This section lists and describes the graphic file formats used for the different 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×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:

This section shows the final cut size of each of the different types of icons, as well as what the placement and drawing area is within the allotted space.

The majority of Eclipse style icons are designed within an area of 16×16 pixels. That is the final cut size of the image. Within that area, a 15×15 pixel space is reserved for the image itself, leaving both a vertical and horizontal line of empty pixels to allow for proper alignment of the image within the user interface. In the size and placement images below, the light blue represents the image area and the bright pink represents the empty pixel area.

If the height and width of the image are an even number of pixels smaller than 16×16 pixels, it is a rule of thumb to center the image within the 16×16 space. For example, a 14×14 pixel image will have a single row of empty pixels on all four sides.

Exceptions to the common 16×16 image size are also detailed below. All sizes are indicated with width before height.

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

In the process described here for creating icons, we use the term 'cut' to mean the action of generating the individual .png files for each icon. This term refers to the fact that the icons are created in a single original .psd file that contains all the icons for a given product (the icon_template.psd file), and then the individual icons are 'cut' out of the file into individual files.

To increase the speed and efficiency of cutting hundreds of icons at a time, a series of cutting actions has been created that, when run in Adobe Photoshop, will automatically guide you through the cutting process for each icon in a matter of seconds. All you need to do is start the action and when prompted, name and save each icon into its proper folder.

To use these actions, download the eclipse_cutting_R3V6.atn file, and then load it into the Actions Palette.

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

We recommend that you work with your development contact to establish file names for each graphic before you begin design work, using the following guidelines:

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

Once your graphics are ready for implementation they should be cut and saved into the folder naming and structure system described below. This system is based on the Eclipse plug-in folder naming and structure. When you compress your files for delivery using this system, they can be easily uncompressed directly into the intended plugin.

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

Each command must provide one full color image. This image will be displayed if the mouse 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 are contributed 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.

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

The tool tips for a command should describe the behavior which occurs if the command is invoked, independent of the current state. For push buttons, the label should describe the result of users pushing the button. For toggle buttons, it should describe its effect when the item is toggled on, and the label should not change depending on the state of the button. In Eclipse, it is recommended that the tool tip for a command uses the same text as that for the command label. For instance, in the following snapshot the behavior of the Show Type Hierarchy button is shown using a tool tip text.

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

When creating a resource, the term "New" should be used in a command or wizard. For instance, "New File", "New Project" and "New Java Class". The term "Delete" should be used when deleting an existing resource.

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

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

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

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

Slush Bucket widgets (also known as the Twin Box design) should flow from the left to the 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 moving objects from the source the selected buckets.

At the top of each wizard is a header, containing a banner graphic and a text area. The banner graphic contains an image representing the wizard task, and should be created with 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. The text area is used to prompt the user for information which is absent, and display error messages if information is invalid. The presence of the header, with banner graphic and text 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.

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

It is not appropriate to display an error message. At this point, the user hasn’t done anything yet.

The initial state of the wizard should be derived from the context where it is opened. For instance, in the New File wizard, the current workbench selection is examined. If it points to a valid project or folder, the wizard will pre-populate the parent field with the parent project or folder name, and put cursor focus in the next field requiring user input. If the user’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 in the field. When the user’s selection is on a file, a wizard may also go through these calculations using the parent folder or project of the file.

Information validation within a wizard should be done in tab order. If the first required field is empty, an informative prompt should be shown in the text area, directing the user to fill in the field. If the first required field is in error, an error message should be shown in 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 disabled until the situation is resolved. When resolution occurs, and all of the information has been provided, the Next or Finish buttons may be enabled.

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

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 the wizard’s header area.

An edit field and Browse…​ button combination should be used whenever an existing object is referenced within a wizard. The edit field is used for direct input of the existing object, and the Browse…​ button is used to browse and select the object from a list of all possible 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 be established between a new object and an old one. The Browse…​ button should be located to the right of the edit field.

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

An example of valid and invalid filtering is shown in the following snapshot.

The New Resource and Import Wizards commonly create new files, folders, and projects within the workbench. If a single file is created, the wizard should open the file in an editor 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.html automatically upon project creation. This will give users an immediate overview of the example: what it does, prerequisites, limitations, steps to take, and so on.

If a new project is created, the wizard should change the active perspective within the workbench to one which is appropriate for the new project type. In Eclipse v2.1, users are prompted 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 without prompting. If users want to switch automatically in the future, they can choose "Do not show this message again" in the confirmation dialog.

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

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 from within the wizard (with a very reasonable set of defaults), the wizard should allow it. If the creation of such resources requires detailed user interaction in order for parent project or folder to be set up correctly, the wizard should not attempt to do this. Instead, the wizard 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 the user to specify the name of the parent project in place makes for a much more usable interaction. In this case, based on the user provided name, the wizard goes off and creates not only the EAR project itself, but also any web projects, etc., that may be needed as well.

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

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

If the editor contains more than one page, a tab control should be used for page activation. The use of this control is demonstrated by the plugin file and html editors.

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

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

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

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

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

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

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 the number of images and commands in the product, and creates a better feel of integration.

A context menu should be used for context sensitive interaction with the objects in an editor. If an object is selected in an editor, and the context menu is opened, the context menu should contain only 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.

For consistency with other editors in Eclipse, each editor should adopt a common order for 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 within the context menu should be kept distinct from one another through the use of separators.

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

One of the primary goals for the platform UI is extensibility. In fact, it is this extensibility which gives you the freedom to add new views, editors, perspectives, and actions to the platform. Of course, extensibility is a two way street. While you may wish to extend the platform, others may wish to extend your view or editor. It is common for one plug-in to add 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 the editor and the platform. To achieve this collaboration, an editor must register each context menu it contains with the platform. It should also define a command filter for each object type in the editor. A command filter makes it easier for one plug-in to add a command to objects in an editor defined by another plug-in. The target is described using object type and attributes. For more information on the implementation of this concept, refer to Creating an Eclipse View.

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 any editor that is currently open on that resource depends on whether the editor has any unsaved changes. If the editor does not contain any changes since the resource was last saved then the editor should be immediately 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:

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 editor tab:

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 first principles.

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

In Eclipse, there is a special relationship between each editor and the Outline view. When an editor is opened, the Outline view will connect to the editor, and ask it for an outline model. 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, or interact 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 in the Outline view. If you select a method or field in the outline, the text declaration of that item will be selected and revealed in the editor. If you select a method or field, and open the context menu, you can interact with the item as a conceptual unit, rather than just a bunch of text.

In general, an editor should provide an outline model to the Outline view if the data within 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 java file or html file.

When an editor has an interaction with the Outline view, notification about location should 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 the editor pane and have the outline view updated.

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

If the edit model contains errors or warnings, they should be indicated in the Outline view. An error or warning image should be added to the item with the error or warning respectively. 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 if neither the container nor any of its descendents have errors. For instance, in the following line, the addFastView method has an error, so an error image is added to the item and its parent.

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

In an editor, task objects are commonly used to mark a location within a document. Once a task has been created, it appears in the Task view. If the task is selected, you may reopen the editor at the location defined in the Task.

A bookmark object can also be used mark a location within a document. Once a bookmark has been created, it appears in the Bookmarks view. If the bookmark is selected, you may reopen the editor at the location defined in the Task.

Editors with source lines of text should have line numbers, and optionally column numbers. Editors should also support Navigate  Goto Line…​ menu allowing users to quickly jump to a desired line. The current line and column numbers should be shown in the status line (column number is optional). It’s optional for the editor to show line numbers for each line in the editor itself.

If the editor contains tables with editable cells, a single-click over a cell should select the current item and put the cell into edit mode. In edit mode, any dropdowns, buttons, or other controls in the cell should be rendered upon the single-click.

In addition, changes should be committed once a user clicks off the cell or hits Enter.

The following are examples of good behaviour for a table cell editor:

If you are doing keystroke by keystroke validation in an editor, use red squiggles to underline the invalid content. When users move the mouse over the red squiggles, display the error text in a fly-over pop up box.

While a resource is opened within the workbench, if modifications are made to it outside of the workbench, we recommend the following approach to handle this situation. When the Save command is invoked in the editor, users should be prompted to either override the changes made outside of the workbench, or back out of the Save operation. If desired, this user prompt can be invoked sooner such as when the editor regains the focus.

A view consists of a title area, a toolbar, a pulldown menu, and an embedded control.

The view label in the title bar must be prefixed with label of the view in Perspective  Show View menu. Given that it is impossible to change the entry in the Show View menu, this means you cannot change the name of a view. However, you can add additional text to the view label, to clarify the state of the view.

In most cases, a view will contain a single control or viewer. However, it is possible to embed more than one viewer or control in the view. If these controls are linked, such that selection in one control changes the input of another, it may be better to separate the view into two. Users will have greater freedom to open one of the results views, as their needs arise. Special relationships can also be set up between these views to support the user task. In addition, this makes it easier for users to create a new perspective with a diverse set of views.

When a view is opened, the input of the view should be derived from the state of the perspective. The view may consult the window input or selection, or the state of another view. For instance, if the Outline view is opened, it will determine the active editor, query the editor for an outline model, and display the outline model.

If the view is used to navigate a hierarchy of resources (i.e., the Navigator or Packages view), the input of the view may be derived from the window input. The window input defines the scope of visible resources within the perspective, and is defined by the user if they select a resource in the Navigator and invoke Open in New Window. For instance, if the Navigator view is opened, it will ask its perspective for the window input. The result is used as the initial input for the view.

Use the view pulldown menu for presentation commands, not selection-oriented commands. These are commands which affect the presentation of the view, but not the objects within the view. Do not put presentation commands in the context menu. For instance, the Sort and Filter commands within the Navigator view affect the presentation of resources, but do not affect the resources themselves.

For consistency with other views in Eclipse, each view should adopt a common order for commands within the pulldown menu. This order is shown in the following table.

The toolbar is used to expose the most commonly used commands in a view. Any command which appears in the toolbar must also appear in the menu (either the context menu or the view menu), but there is no need to duplicate every command in the menu within the toolbar.

A context menu should be used for context sensitive interaction with the objects in a view. If an object is selected in a view, and the context menu is opened, the context menu should contain only actions which are appropriate for the selection. Actions which affect the presentation of the view should not appear in the context menu.

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

The New category contains actions which create new objects. The Open category contains actions which open the selection in an editor. Navigate contains actions to refocus the view input, or reveal the view selection in another view. And the other categories are self explanatory.

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

An object in one view may be visible in many other views or editors. For instance, a .java file is visible in the Navigator, the Hierarchy view, and the Packages view. To the user, these objects are all the same, regardless of location, so the context menu for the .java file should be the same in each.

Implementation tip: To achieve a consistent context menu, plug-in developers which introduce a new object type should contribute commands to the context menu using an action group (ActionGroup class), a Java class which populates the context menu. If this approach is used, the action group can be reused by other views where the same objects appear.

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

In the platform, the menu and toolbar for a view are automatically extended by the platform. In contrast, context menu extension is supported in collaboration between the view and the platform. To achieve this collaboration, a view must register each context menu it contains with the platform. It should also define a command filter for each object type in the view. A command filter makes it easier for one plug-in to add a command to objects in a view defined by another plug-in. The command target is described using object type and attributes. For more information on the implementation of this concept, refer to Creating an Eclipse View.

The window menu bar contains a number of global commands, such as Cut, Copy, and Paste within the Edit menu. These commands target the active part, as indicated by a shaded title area. If these commands are supported within a view, the view should hook these window commands, so that selection in the window menu bar or toolbar produces the same result as selection of the same command in the view.

A complete list of the global commands and built-in menus as declared in IWorkbenchActionConstants.java (see below).

Although a view can’t directly contribute to the main menubar or toolbar in Eclipse v2.1, it can still cause commands to appear there using "action set / part associations" (the actionSetPartAssociations extension point) which lets you associate action sets with particular parts (views or editors). For example, the Java tooling in Eclipse uses this for the Package Explorer. All commands for the view (or editor) should be made available on the main menubar, and only frequently used commands are on the context menu. In addition, the primary perspective(s) for such views (e.g., the Java and Java Browsing perspectives) should already have these action sets associated with the perspective, to improve UI stability.

One of the primary goals for the platform UI is to provide efficient interaction with the workspace. In the platform this is promoted by saving the state of the workbench when a session ends (the workbench is shut down). When a new session is started (the workbench is opened), this state is restored, reducing the time required for the user to get back to work.

If a view has a static input object, in the sense that its input is not derived from selection in other parts, the state of the view should be persisted between sessions. If a view has a dynamic or transient input object, there is no need to persist its state between sessions. Within the workbench, the state of the Navigator view, including the input and expansion state, is saved between sessions. For more information on the implementation of persistence, see Creating an Eclipse View.

If the user opens a new perspective, the initial layout of views will be defined by the perspective type (i.e., Resource, Java). This layout is performed in the perspective factory, a Java class associated with the perspective type. When the perspective is initialized, it consists of an editor area with no additional views. The perspective factory may add new views, using the editor area as the initial point of reference.

The size and position of each view is controlled by the perspective factory. These attributes should be defined in a reasonable manner, such that the user can resize or move a view if they desire it. An important issue to consider is the overall flow between the views (and editors) in the perspective. For example, initially the navigation views may be placed to the left of the editor area, outline views may be placed either to the right of the editor area or below the navigation view, and other supporting views may be placed below and to the right of the editor area.

A perspective should have at least two parts, including the visible views and the editor area. If this is not the case, then the perspective should be re-examined to determine if it is better suited as a view or editor.

In some scenarios, it may be undesirable to have an editor area within a perspective. In this case, the perspective factory should hide the editor area, using the existing java methods. It is not acceptable to resize the editor area to a point where it is no longer visible. If the user does open an editor in the perspective, for whatever reason, they will be unable to see or resize it.

When the editor area is programmatically hidden, if the user opens an editor in the perspective, the editor area will become visible. The view that occupied the editor area before will be shrunk. Therefore, it is important to define a non-empty editor area even when the editor is programmatically hidden.

The perspective factory may add actions to the File  New, Window  Open Perspective, and Window  Show View menus. It is also possible to add one or more command sets to the window. In each case, you should choose commands which are relevant to the task orientation of the perspective.

The File  New menu should be populated with wizards for the creation of objects commonly used in the task. For instance, in the Java perspective the File  New menu contains menu items for the creation of packages, classes, and interfaces.

The Window  Show View menu should be populated with the initial views in the perspective, as well as any extra views that may be important for the task at hand. The Navigate  Show In menu should be used to allow users to navigate in their contents.

The application development lifecycle should be considered when populating the the Window  Open Perspective menu. The development of most applications follow a well defined lifecycle, from designing / modeling, to editing / creating, to debugging / testing, to assembling /deploying. Each perspective will fall into one of these steps. The Open Perspective menu should be used to link the current perspective to perspectives that support tasks immediately downstream of the current one, as well as tasks further upstream, to allow for iterative development.

For instance, the Java perspective is used in a larger lifecycle, involving Java and Debug tasks. The Window  Open Perspective menu is populated with each of these perspectives.

A command should open a new perspective only if the user explicitly states a desire to do so. If the user does not state a desire to do so, opening a new perspective may cause loss of context for the user.

For instance, imagine a scenario where the user selects an object and invokes a command. In the perspective where the command is invoked, the user may have a set of views and editors open. These represent the working state, or context, of the user. If a new perspective is created, that context will be left behind, forcing the user to recreate the context. This is time wasted.

In some cases, a new perspective is opened as the side effect of another command. For instance, if users start debugging their application code, they may be switched to the Debug perspective. If this behavior is implemented, the user should have the option to turn this behavior off. The option can be exposed in the command dialog, or within a Preference page.

If a new perspective is opened, it may be opened within the current window, or in a new window. The user controls this option using the Workbench preferences. If code within a plug-in opens a new perspective, the plug-in should honor the user preference.

With regard to command contributions applied to the New, Open Perspective, and Show View menus, the list of wizards, perspectives, and views added as shortcuts to these menus should be at most 7 plus / minus 2 items.

Each workbench window contains a menu bar and toolbar. These are pre-populated by the platform, but a plug-in developer may add additional items to each. This is done by defining an action set, a set of task oriented actions which the user can show or hide. The actions within an action set may be distributed throughout the window menu bar and toolbar.

The window menu bar contains a number of pulldown menus: File, Edit, Navigate, Project, Window, and Help. Each of these has a different purpose, which will be explained in the following paragraphs. For consistency with the action sets contributed by other plug-ins, the commands within an action set should conform to the existing distribution of actions in the window. There is no need to group the actions in a separate pulldown menu of the menu bar.

The File menu contains file oriented actions, such as Save, Close, Print, Import, Export and Exit. The contents of the File  New menu are determined by the perspective type. However, the user may add or remove items using the Window  Customize Perspective…​ menu item. The contents of the Import and Export dialogs are populated with every import and export wizard, respectively.

The Edit menu contains editor oriented actions, such as Undo, Redo, Cut, Copy, and Paste. These actions target the active part (as indicated by a shaded title bar). It is very common for an editor to add items to this menu. However, it is uncommon for an action set to add actions to the Edit menu; action sets tend to be global in nature, while the edit menu targets a specific part, and interaction with the data in that part.

The Navigate menu contains navigational actions such as Go to, Open Type, Show In, to enable users to browse laterally or drill down in their code.

The Project menu contains actions which apply to the contents of the workspace, such as Rebuild All and Open Type. An action set may add actions which search the entire workspace, generate project info and so on.

The Window menu contains actions which apply to window management and system preferences. It also contains the Open Perspective and Show View submenu which contains actions affecting the state of the window contents.

The toolbar contains the most commonly used actions of the menu bar. In reflection of this, you should contribute actions to the menu bar first, and then to the toolbar if they will be frequently used.

The contents of each action set should be defined using a task oriented approach. For instance, the Java action set contains actions to create a new package, class and interfaces. It also contains a command to open an editor on a class, Goto Type. These form a cohesive set of related actions, which can be turned on and off by the user, depending on the active task.

The size of an action set is also important. If an action set is too large, it will flood the menu or toolbar, and reduce the users ability to customize the menu and toolbar. At the same time, if an action set is too small, the user may find customization of the menu and toolbar is too labor intensive. Break an action set up when it has more than about 7 items.

There is no magic number for the size of an action set, but it should be carefully designed to contain the smallest possible semantic chunking of actions. Avoid the temptation to provide only one action set for an entire plug-in.

An action set can be used to share a set of actions between two or more views and editors. For instance, a Java Refactor action set may be applicable to the selection within a Java Editor, an Outline view, and a Hierarchy View. In this situation the actions can be shared by defining an action set extension for the workbench. Once this action set has been defined, it can be automatically included in a perspective by the perspective developer, or added to a perspective by the user. An action set should not be used to promote command from a single view to the window menu bar and toolbar. This simply clutters up the user interface.

The set of visible command in a window may be changed by invoking Window  Customize Perspective. Within the resulting dialog, you can add or remove items from the File  New menu, Window  Open Perspective menu, or Window  Show View menu. It is also possible to add or remove action sets. In general, the visible action sets should be controlled by the user, and should never be changed programmatically. There are two reasons for this. First, users like to control the environment, not be controlled. And second, the user is in the best position to understand the active task, and the appropriate action sets for its completion.

A common example of a command which may be added to an action set is Navigate  Open Type. This command can be used to open an editor on a type which is not visible in the current window, and is a form of lateral navigation. In general, all Open actions which take the form should be added to the Navigate menu, for consistency.

If there is a need for a plug-in to show non-modal contextual information in the status bar area, always use the global status bar. For example, editors use the global status bar to show the current line and column number.

For Tree and Table widgets that have a checkbox associated with a cell item, users can either select the item or change the checkbox state. Changing the current selection should not automatically change the check state of the selected item. However, the current selection should be set to a given item when its check state is changed (e.g., users click on the checkbox associated with the item).

This is done by adding an extension to the plug-in registry.

If object contributions are made to the context menu, try to qualify the target object as much as possible, to avoid adding the command to the wrong objects in the Navigator. For instance, a Java command may target Files with a .java extension, or IProjects with a Java nature. It will cause confusion if Java actions appear on non-java objects.

Some actions are a reflection of tool use, rather than object type. For instance, a repository plug-in may provide actions for file check in, check out, etc. These actions should appear on the resources in the Navigator only if the user has actively chosen to use the repository tool. To control the visibility of these actions, the plug-in should apply a project nature to the managed resources, and use the project nature attribute in all context menu contributions.

For more information on command filtering, refer to Creating an Eclipse View. The standard attributes for resources are defined in IResourceActionFilter.java (see below).

The standard attributes for project filtering are defined in IProjectActionFilter.java.

In Eclipse, the use of a Navigate  Show In command is a common way to link the selection in one view to the input of another. For instance, a "Show in Package Explorer" command is visible in the context menu for a selected class in the source editor. When invoked, the class in the source editor is selected and revealed in the Package Explorer view. This approach should be used as a general, non intrusive pattern for view or editor linking. It is context sensitive, and reflects the intentions of the user.

A Navigate  Show In Navigator command should be included in any view where a resource may appear. If invoked, the command should select and reveal the resource in the navigator.

A new task, error or warning can be created using the Marker Manager services from the Core Resources Management plugin.

The Tasks view is a table, containing columns for the task image, completion status, priority, description, resource, and line number. The description text of each marker should be short and concise, so that it will fit in the status line of Eclipse.

You can contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry.

If object contributions are made to the context menu, try to qualify the target object as much as possible, to avoid adding the command to the wrong objects in the Tasks view. At an implementation level, each object in the Tasks view is a marker, a general mechanism for associate notes with a resource. Use the attributes within IMarkerActionFilter.java to control the visibility of Task object actions (see below). For more information on command filtering, refer to Creating an Eclipse View.

In an editor, task objects are commonly used to mark a location within a document. Once a task has been created, it appears in the Task view. If this task is selected (via double clicking), you should reopen the editor at the location defined in the task. The focus should be changed from the Task view to the editor.

If appropriate, support for the creation of new task objects in an editor should be implemented by the editor. For more information on this, see Editors.

Plug-ins should support F1 keyboard command and link it to an infopop that gives a detailed description of the selected item in the Task view.

Use ContainerSelectionDialog when you want to select an IContainer (IFolder/IProject) from the workspace.

You can restrict the resource to be within a project/folder by passing the respective object as the second parameter for the constructor.

The ContainerSelectionDialog allowed you to select only one resource that too it should be a container. If you want to select multiple resources including files, then ResourceSelectionDialog is the one you should be using.

The ResourceSelectionDialog is good when you want to present the entire set of resources under a parent and allow the user to select multiple resources. But if you have a set of resources and want the user to select only one from that, then probably you should be using ResourceListSelectionDialog.

The above Dialogs are good to selecting workspace resources. But what if I have some elements on my own and I want to select from that? The first dialog you would be using is ElementListSelectionDialog. The user can select an element from the set. You have to pass the elements as an array and supply a label provider to render the element. The user can filter using wildcards as well.

If you want the user to select multiple elements from the given set, then ListSelectionDialog is the one to use. It is basically a single column TableViewer with SWT.CHECK style applied. You have to supply your own ContentProvider and LabelProvider for the TableViewer. It also has Select All and Deselect All buttons.

If you have your items in a tree structure and want to select few elements from them, then CheckedTreeSelectionDialog is your choice. You have to bring your own content and label provider and the input.

ElementTreeSelectionDialog is the same as the CheckedTreeSelectionDialog except that it will allow you to select a single element in the whole tree rather than multiple elements.

Have you used the Open Type (Ctrl+Shift+T) or Open Resource (Ctrl+Shift+R) dialog? It’s similar to the ElementListSelectionDialog, but it has more features. It can select multiple items, display a detail pane about the item that is currently selected, it can even remember your previous selections; store them in history and present them before the other choices. To have that functionality, you have to extend the abstract class FilteredItemsSelectionDialog and provide the necessary implementation.

In the simplest case, any plug-in which needs to expose an option to the user will define a single preference page. This preference page should contain all of the options for the plug-in, until the number of options starts to overload the page. At that point a nested design for preference pages should be adopted.

In a nested design, a root preference page is added to the preference dialog, and then sub pages are added to the root preference page. The root preference page should never be blank. Instead, it should contain the most commonly used preferences, or those preferences which have a wide spread effect upon the plug-in behavior. Beneath the root page, a sub page should be created for each major chunk of functionality within the plug-in.

There is no reason to set the focus in a preference page, because focus is always set to the tree, by the Eclipse platform, after the preference page is made visible.

Each new plug-in should integrate its plug-in preferences, wizards, and views into existing preference, wizard, and view categories where it makes sense, rather than the blind creation of new categories for itself.

It is very important to design custom decorators that don’t conflict with basic decorations provided by different Eclipse views. For example, the package explorer view decorates Java files with problem markers (a problem marker is placed at the bottom left hand corner) if there are compilation errors. It is a bad practice to decorate resources with custom decoration exactly at the position of a problem marker and developers should avoid this. If the custom decoration is performed at the bottom left corner, then custom decoration and the problem marker decoration, if any, conflict each other and hence users will not be able to view the decorations. The solution to the above mentioned problem is to provide a custom image decoration at the bottom right corner which does not conflict with the basic image decoration provided by Eclipse. The top left corner is the second best place although it conflicts with the binary project decorator. The bottom left and top right should be avoided as they are decorated outside of the decorator mechanism.