Naming Conventions

ns a number of views, including the Navigator, Outline, Properties, Tasks, and Bookmarks view. Eclipse also contains a default text editor and a Resource perspective. As a plug-in developer, you should try to add new actions to the existing parts. This leads to better integration with the platform, and the existing knowledge of the user. Guideline 12.1 If appropriate, add actions to standard components of Eclipse using the plug-in registry. When extending the standard components such as the Navigator, Outline, Properties, Tasks, and Bookmark views, make sure your specialized components carry over the base component's characteristics (drag and drop support, keyboard navigation, selection behaviour, etc.) Guideline 12.2 If you subclass or copy any of the standard components, always carry over the standard components' characteristics. The Navigator View The Navigator is used to navigate the workspace, create new resources, modify resources, and open an editor on a resource. Plug-in developers may contribute new actions to the menu, toolbar, and context menu. Adding Actions This is done by adding an extension to the plug-in registry. Guideline 13.1 Add actions to the Navigator View menu, toolbar, and context menu using 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 IFiles 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 only appear on the resources in the Navigator 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). public interface IResourceActionFilter extends IActionFilter { public static final String NAME = "name"; public static final String EXTENSION = "extension"; public static final String PATH = "path"; public static final String READ_ONLY = "readOnly"; public static final String PROJECT_NATURE = "projectNature"; } The standard attributes for project filtering are defined in IProjectActionFilter.java. public interface IProjectActionFilter extends IResourceActionFilter { public static final String NATURE = "nature"; public static final String OPEN = "open"; } Guideline 13.2 Use the attributes defined in IResourceActionFilter.java and IProjectActionFilter.java to control the visibility of context menu actions in the Navigator. Integration with Other Views and Editors 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. Guideline 13.3 Use a "Navigate -> Show In Navigator" command in each view, to link resources back to the Navigator. The Tasks View The Tasks view is used to display the current tasks, errors and warnings in the workspace. A plug-in developer may contribute new tasks, errors, and warnings to the workspace, and rely upon the Tasks view to display those objects. You can also contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry. Adding Tasks A new task, error or warning can be created using the Marker Manager services from the Core Resources Management plugin. Guideline 14.1 Add markers (tasks, errors and warnings) to the Tasks view 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. Guideline 14.2 The description text of each marker should be short and concise, so that it will fit in the status line of Eclipse. Adding Actions You can contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry. Guideline 14.3 Add actions to the Tasks view menu, toolbar, and context menu using 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. public interface IMarkerActionFilter extends IActionFilter { public static final String TYPE = "type"; public static final String SUPER_TYPE = "superType"; public static final String PRIORITY = "priority"; public static final String SEVERITY = "severity"; public static final String DONE = "done"; public static final String MESSAGE = "message"; } Guideline 14.4 Use the attributes defined in IMarkerActionFilter.java to control the visibility of context menu actions in the Tasks view. Integration with Other Views and Editors 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. Adding F1 Help to Task View 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. Guideline 14.5 Support F1 keyboard command and link it to an infopop that gives a detailed description of the selected item in the Task view. The Preference Dialog The Preference Dialog is used to edit the global preference for a feature in the workbench. A new preference page should be created when you need to expose global options to the user. For instance, the global preferences for Java compilation are exposed as a group of preference pages in the Preference Dialog. If these preferences are changed, they affect the entire Java plug-in. Guideline 15.1 Global options should be exposed within the Preferences Dialog. A preference page should not be used to expose the local options for a particular instance of a view, editor, or window. In this situation, the user will look to the menu and toolbar of the control itself to customize it. If these options are exposed in the Preference Dialog, it will blur the location of customization, and confuse the user. Guideline 15.2 Expose the preferences for a particular view, editor or window in the view itself, via a menu or tool item. Preference Page Design 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. Guideline 15.3 Start out with a single preference page. Then evolve to more if you need to. 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. Guideline 15.4 If you create a preference group, use the root page for frequently used preferences, or those preferences which have wide spread effect. Specialize within the sub pages. The root preference page should not be blank. 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. Guideline 15.5 Attempt to integrate plug-in preferences, wizards, and views into existing categories for a new plug-in first, before considering the creation of a new category. The Outline View In Eclipse, there is a special relationship between an 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 edit data, or interact with the edit data at a higher level of abstraction. If you are an editor developer, the relationship between an editor and the Outline view is important. For more information on the collaboration between these two, see Editors. The Properties View The Properties view shows the properties for the active part in the workbench, or the selection within that part. These properties are supplied by the active part itself. The Properties view is simply a container for their presentation. Within Eclipse, the properties for an object can be exposed using a Properties dialog, or the Properties view. The Properties view is commonly used to edit the properties for a set of objects in an editor, where quick access to the properties is important, and you switch from one object to another quickly. For more information on the use of the Properties view, or Properties dialog, refer to Properties. The Bookmarks View The Bookmarks view is used to bookmark files, and open them quickly. A plug-in developer may contribute new bookmarks to the workspace, and rely upon the Bookmarks view to display those bookmarks. You can also contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry. In an editor, bookmark objects are commonly used to mark a location within a document. Once a bookmark has been created, it appears in the Bookmarks view. If this bookmark is selected, you may reopen the editor at the location defined in the bookmark. If appropriate, support for the creation of new bookmark objects should be implemented by the editor. For more information on this, see Editors. The Text Editor The Text Editor is commonly used to edit text files. A plug-in developer can contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry. For more information on this, see Editors. The Resource Perspective The Resource perspective contains a Navigator, Outline, Task view, and editor area. Plug-in developers may contribute a new command, action set, or view to the Resource perspective. For more information, refer to Perspectives. Flat Look Design The Eclipse platform provides a Web user interface, also known as Flat Look, design alternative for implementing content editors. For example, the editor in the Eclipse plug-in development environment (PDE) perspective uses Flat Look. The Flat Look design may be more suitable for certain type of user tasks, and more appealing to certain user profile. However, this design should not be used just because it provides a different look than the native platform look and feel. The use of Flat Look design should be considered in the context of the supported user scenarios. This design is usually a good fit for extensive property and configuration editing, such as editing Eclipse's plugin.xml file, and J2EE Web application's deployment descriptors. Guideline 16.1 Use Flat Look design for user scenarios that involve extensive property and configuration editing. When required, use a "More..." button for navigation purpose (function similar to a hyperlink). On the overview page, initially expand basic or core sections, but collapse advanced sections. On non-overview pages, provide a "Home" icon which takes users back to the overview page Guideline 16.2 Have the core sections on the overview page expanded, and provide a "Home" icon on other pages to take users back to the overview page. Don't use tabs within a Flat Look editor tab. Use an alternative design or rendering of the tabs. When applicable, always provide a "Source" tab. Assign mnemonics for sections, controls, etc. for keyboard navigation. Editor and Outline View Interaction Plug-ins that use Flat Look design for content editor should provide support for full two way interactions between the editor and outline view. In the outline view, use grouping elements corresponding to tabs in the content editor for the organization of the tree view. Guideline 16.3 Use grouping elements corresponding to tabs in the Flat Look content editor for the organization of the tree view in outline view. The Tao of Resource In Eclipse, the notion of a tool disappears. In its place, is the idea of a universal tool platform - an open, extensible IDE - where tool plug-ins are added to extend the capabilities of the platform. These plug-ins "teach" Eclipse how to work with things - java files, web content, graphics, video - almost anything you can imagine. At an implementation level, these plug-ins communicate using resources (projects, folders, and files). The resource is the common medium for integration between plugins and external tools. The resource concept was developed for a number of reasons: Integration between a plug-in from one vendor, and a plug-in from another, is only possible if there is a common, well known data abstraction. Integration with external tools is only possible if everything, at some level, is a file. Resources are also important at the UI level. If an object command, decorator, or property page contribution is made to an IResource, the platform will ensure that this contribution is visible in any view or editor where the resource appears. For instance, a .java file will be visible in the Navigator, the Hierarchy view, and the Packages view. To the user, the .java file is the same object, regardless of the view where it appears, so the object appearance, context menu, and properties should be consistent in each view. In some cases, the implementation of a particular view or editor may wrap a resource within another object, for presentation purposes. If the wrapper is equivalent to a resource, it is important to expose this equivalence to the platform. If the resource is exposed, the platform may apply resource contributions to the resource equivalent object. This ensures presentation consistency for an object in the platform. The underlying resource for an object is exposed by implementing IAdaptable on the model object, and answering an IContributorResourceAdapter. For more information on the implementation of an IContributorResourceAdapter, refer to Eclipse Corner. Guideline 17.1 Expose the resource for resource equivalent model objects using an IContributorResourceAdapter. Accessibility In a view, editor, or other control, every features should be accessible using a mouse or the keyboard. In a dialog or wizard, a shortcut key should be defined for each button or control. The shortcut key should be displayed with an underline beneath the appropriate shortcut character. Guideline 18.1 All of the features provided by a tool should be accessible using a mouse or the keyboard. Standard Accelerators The Eclipse platform has defined a large number of shortcut keys. Plug-in developers should make sure that the existing shortcut keys do not conflict with the shortcut keys defined in the plug-in. Key {Key} by itself SHIFT+{Key} CTRL+{Key} CTRL+SHIFT+{Key} ALT+{Key} CTRL+ALT+{Key} A Edit / Select All B Project / Build (View) Bookmarks C Edit / Copy D (JDT editor) Display E (JDT editor) Next Problem (JDT editor) Previous Problem F Edit / Find / Replace G H Edit / Search I J K (View) Tasks L Edit / Go to Line M (JDT editor) Add Import (JDT) Refactor / Move N File / New / Other (View) Navigator O (JDT editor) Organize Imports (View) Outline P File / Print (View) Properties Q (JDT editor) Inspect R S File / Save File / Save All Window / Switch to Editor T (JDT) Open Type U V Edit / Paste W X Edit / Cut (JDT) Refactor / Extract method Y Edit / Redo (JDT) Refactor / Redo Z Edit / Undo (JDT) Refactor / Undo Space (JDT editor) Content Assist Backspace Windows: Undo Tab (JDT editor) Shift Right (JDT editor) Shift Left Insert Windows: Paste Windows: Copy Delete Edit / Delete Windows: Cut Edit / Delete Home End Page Up Page Down Insert Delete Hyphen (-) Show System Menu Show View Menu Left Arrow Right Arrow Up Arrow Down Arrow F1 Help Help Help Help F2 (Navigator view) Rename, (JDT editor) Open JavaDoc F3 (JDT editor) Open on Selection F4 (JDT editor) Open Type Hierarchy File / Close All File / Close F5 (Navigator view) Refresh, (Properties view) Refresh, (Debug) Step Into F6 (Debug) Step Over Next Editor Previous Editor F7 (Debug) Run to Return Next View Previous View F8 (Debug) Resume F9 F10 (Debug) Relaunch last F11 (Debug) Debug (Debug) Run F12 Activate Editor Activate Editor Best Practices In this section, we provide examples of best practices for designing and implementing some common user interactions within the Eclipse platform. Syntax and Compilation Error Handling When designing editors that provide syntax or compilation checking support, follow the Java tooling design in the Eclipse platform. Provide on the fly syntax checking if possible. Use red "squiggle" to indicate where the potential error is located in the source code. Use a red box on the side bar on the right side to indicate the approximate error position in the file. Use a prominent marker on the upper right hand corner to indicate that the file contains errors or warnings. Use red color to indicate errors, and use yellow to indicate warnings. After users perform a save operation, user a more prominent marker on the left hand side margin to indicate errors and warnings in the file. When using the mouse pointer to hover over the marker, the description text should be displayed. In addition, show the icon decorator in the content editor tab. In the tree view that shows the resource in the Eclipse workspace, use icon decorator to indicate errors or warnings associated with this resource, and propagate the icon decorator indication up to the parents of the resource in the tree view. Finally, an entry should be added to the Task view to list the errors and warnings. Coding Assistance In addition to supporting the standard content assist in an editor, editors should exploit the use of Quick Fixes and Quick Assist. Use the light bulb marker on the left hand side margin to provide suggestions on how to fix problems with the source code. Users can click on the light bulb or use Edit -> Quick Fix menu item to invoke this command. Even when there are no syntax errors in the file, users should be able to obtain certain quick assistance with their code using the Quick Fix mechanism. For example, assigning an expression to a local variable. If an editor is used for writing code in a given programming language, hyper-linked code support should be enabled. While using the mouse pointer to hover over the source code, pressing the Ctrl key will turn the programming language constructs such as class, method, and field identifiers into clickable links to the corresponding declaration. When possible, a plug-in should provide refactoring support at the programming language or application development level. For example, if users rename a method in a Java class, refactoring support should enable users to automatically find and fix up all references. If users change the URL for a given resource in a Web application, refactoring support should enable users to automatically update the references to the modified URL. Context Menu Here is one suggested process to reason why a menu item should be added or removed from the context menu. The objective is to reduce the number of context menu items to no more than 20. First, remove menu items that are not sensitive to selections. Second, remove menu items that are not frequently used. Third,?examine the items that are not sensitive?to selection but are frequently used. Add at most of 5 of these items back. Fourth,?remove all disabled menu items, except for clipboard operations such as copy and paste, and team, compare and replace submenus. Fifth, remove menu items that are frequently used, selection sensitive, but have a dominant keyboard shortcut key defined, except for clipboard and save operations. Labels, Fonts and Layout for Flat Look Design For Flat Look design, when using buttons with ellipses (except for the "More..." button), it should pop up a secondary window which can be a dialog box or a wizard. Use Title capitalization for section titles. The distance between section columns should be 32 pixels. On pages with listbox on the left hand side, the distance be between the list box and the right-hand column (e.g. showing properties for a selected listbox item) should be 10 pixels. For labels and fields, use RGB value (160, 160, 164) for enabled state, RBG value (0, 0, 0) for read-only state, and RBG value (128, 128, 128) for disabled state. For listbox control, use RBG value (0, 0, 0) for the border to indicate enabled state, use RBG value (128, 128, 128) for disabled state. Decorators Enabling and disabling the decorators are extremely useful when the decorations performed by two or more decorators conflict with each other. For example, the CVS plug-in might decorate the base image by superimposing the base image with a custom image while the "Decorate Example" plug-in might superimpose a different custom image at the same position thereby conflicting with the CVS plug-in decoration. If the decoration performed by two different decorators on the same resource conflict, users should appropriately enable / disable different decorators to get the required decoration. Implementation tip: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 Checklist For Developers Here is a checklist for developers who are developing UI plugins. This could be used for certification purposes. General UI Guidelines The Spirit of Eclipse Guideline 1.1 Follow and apply good user interface design principles: user in control, directness, consistency, forgiveness, feedback, aesthetics, and simplicity. Guideline 1.2 Follow the platform lead for user interface conventions. Guideline 1.3 Be careful not to mix UI metaphors. It may blur the original concept, and your own application. Guideline 1.4 If you have an interesting idea, work with the Eclipse community to make Eclipse a better platform for all. Capitalization Guideline 1.5 Use Headline style capitalization for menus, tooltip and all titles, including those used for windows, dialogs, tabs, column headings and push buttons. Capitalize the first and last words, and all nouns, pronouns, adjectives, verbs and adverbs. Do not include ending punctuation. Guideline 1.6 Use Sentence style capitalization for all control labels in a dialog or window, including those for check boxes, radio buttons, group labels, and simple text fields. Capitalize the first letter of the first word, and any proper names such as the word Java. Language Guideline 1.7 Create localized version of the resources within your plug-in. Error Handling Guideline 1.8 When an error occurs which requires either an explicit user input or immediate attention from users, communicate the occurrence with a modal dialog. Guideline 1.9 If a programming error occurs in the product, communicate the occurrence with a dialog, and log it. Visual Design Consistency Guideline 2.1 Re-use the core visual concepts to maintain consistent representation and meaning across Eclipse plug-ins. Icon Palettes Guideline 2.2 Use the Eclipse 256 color palette for creating the active or selected state of all icon types. Guideline 2.3 Use the Eclipse 8 color palette for creating the enabled state of perspective, view, toolbar, toolbar wizard, and local toolbar icons. Guideline 2.4 Use the Eclipse 2 color palette for creating the disabled state of toolbar, toolbar wizard, and local toolbar icons. Icon Types Guideline 2.5 Use the appropriate icon type in the location it is designed for within the user interface. Icon Size & Placement Guideline 2.6 Follow the specific size specifications for each type of icon. Guideline 2.7 Cut the icons with the specific placement shown to ensure alignment in the user interface. Icon Positioning Guideline 2.8 Follow the positioning guidelines for the different types of icons for optimal alignment of these elements relative to one another. Icon Positioning Guideline 2.9 Use the Eclipse special blue 183 color palette for creating wizard graphics. Wizard Size & Placement Guideline 2.10 Follow the specific size specifications for wizard graphics. Guideline 2.11 Cut the wizard graphics with the specific placement shown to ensure alignment in the wizard banner area. Implementation Conventions Guideline 2.12 Follow the predefined directory structure and naming convention. Guideline 2.13 Keep the original directory names provided. Guideline 2.14 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. 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). 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 the context requires a different file format. Guideline 2.21 Keep the original file names provided. Component Development Commands Guideline 3.1 Each command must have a label, tool tip, and full color image. The label and tool tip must use Headline style capitalization. Guideline 3.2 The command tooltip should describe the result of the command, not the current state of the command. Use the text same as that for the command label. Guideline 3.3 Adopt the labeling terminology of the workbench for New, Delete and Add commands. Guideline 3.4 An command should only be enabled if it can be completed successfully. Guideline 3.5 Command enablement should be quick. If command enablement cannot be quick, enable the command optimistically and display an appropriate message if the command is invoked, but cannot be completed. Dialogs Guideline 4.1 When a dialog opens, set the initial focus to the first input control in the container. If there are no input controls, the initial focus should be assigned to the default button. Guideline 4.2 Slush Bucket widget (or Twin Box) should flow from left to right with the source objects on the left hand side. It should have the >, >, << control buttons in this order. Wizards Guideline 5.1 Use a wizard for any task consisting of many steps, which must be completed in a specific order. Guideline 5.2 Each wizard must contain a header with a banner graphic and a text area for user feedback. It must also contain Back, Next, Finish, and Cancel buttons in the footer. Guideline 5.3 Start the wizard with a prompt, not an error message. Guideline 5.4 Seed the fields within the wizard using the current workbench state. Guideline 5.5 Validate the wizard data in tab order. Display a prompt when information is absent, and an error when information is invalid. Guideline 5.6 Only enable the Next / Finish buttons if all required information in the dialog is present and valid. Guideline 5.7 Remove all programming message ID's from wizard text. Guideline 5.8 Use a Browse Button whenever an existing object is referenced in a wizard. Guideline 5.9 If a new file is created, open the file in an editor. If a group of files are created, open the most important, or central file in an editor. Open the readme.html file upon creation of an example project. Guideline 5.10 If a new project is created, prompt users and change the active perspective to suit the project type. Guideline 5.11 If a new object is created, select and reveal the new object in the appropriate view. Guideline 5.12 Create folder objects in a wizard if reasonable defaults can be defined. 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 Guideline 6.1 Use an editor to edit or browse a file, document, or other primary content. Guideline 6.2 Modifications made in an editor must follow an open-save-close lifecycle model. Guideline 6.3 Only one instance of an editor may exist, for each editor input, within a perspective. Guideline 6.4 It must be possible to open a separate instance of an editor for each different input. Guideline 6.5 The editor should be labeled with the name of the file, document, or input being edited. 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. Guideline 6.7 All of the commands, except for the obvious commands, available in the editor should be added to the window menu bar. Guideline 6.8 Use the standard format for editor contributions in the window menu bar. Guideline 6.9 If an editor has support for Cut, Copy, Paste, or any of the global commands, these commands must be executable from the same commands in the window menu bar and toolbar. Guideline 6.10 Fill the editor toolbar with the most commonly used items in the view menu. Guideline 6.11 Fill the context menu with selection oriented commands. Guideline 6.12 Use the standard format for editor context menus. Guideline 6.13 Fill the context menu with a fixed set of commands for each selection type, and then enable or disable each to reflect the selection state. 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. Guideline 6.16 If the input to an editor is deleted, and the editor contains no changes, the editor should be closed. 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. Guideline 6.18 If the resource is dirty, prefix the resource name presented in the editor tab with an asterisk. 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. Guideline 6.20 If the data within an editor is too extensive to see on a single screen, and will yield a structured outline, the editor should provide an outline model to the Outline view. Guideline 6.21 Notification about location between an editor and the Outline view should be two-way. A context menu should be available in the Outline view as appropriate. Guideline 6.22 An error or warning image should be added to items 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. Guideline 6.23 If appropriate, implement the "Add Task" feature in your editor. Guideline 6.24 If appropriate, implement the "Add Bookmark" feature in your editor. Guideline 6.25 Editors with source lines of text should show the current line and optionally column numbers the status line. It's optional for the editor to show line numbers for each line in the editor itself. Guideline 6.26 Table cell editors should support the single-click activation model, and in edit mode, they should render complex controls upon single-click. Guideline 6.27 Changes made in a table cell editor should be committed when a user clicks off the cell or hits the "Enter" key. Selection should be cancelled when user hits the "Esc" key.First letter navigation should be supported as a cursoring mechanism within a cell. Guideline 6.28 When performing fine-grain error 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. Guideline 6.29 Use the Task view to show errors found when the Save command is invoked. Guideline 6.30 If modifications to a resource are made outside of the workbench, users should be prompted to either override the changes made outside of the workbench, or back out of the Save operation when the Save command is invoked in the editor. Views Guideline 7.1 Use a view to navigate a hierarchy of information, open an editor, or display the properties of an object. Guideline 7.2 Modifications made within a view must be saved immediately. Guideline 7.3 Only one instance of a view may exist in a perspective. Guideline 7.4 A view must be able to be opened in more than one perspective. Guideline 7.5 A view can be opened from the Window > Show View menu. Guideline 7.6 The view label in the title bar must be prefixed with the label of the view in the Perspective > Show View menu. Guideline 7.7 If a view contains more than one control, it may be advisable to split it up into two or more views. Guideline 7.8 When a view first opens, derive the view input from the state of the perspective. Guideline 7.9 If a view displays a resource tree, consider using the window input as the root of visible information in the view. Guideline 7.10 Use the view pulldonw menu for presentation commands, not selection-oriented commands. Guideline 7.11 Use the standard order of commands for view pulldown menus. Guideline 7.12 Put only the most commonly used commands on the toolbar. Any command on a toolbar must also appear in a menu, either the context menu or the view menu. Guideline 7.13 Fill the context menu with selection oriented actions, not presentation actions. Guideline 7.14 Use the standard order of commands for view context menus. Guideline 7.15 Fill the context menu with a fixed set of commands for each selection type, and then enable or disable each to reflect the selection state. Guideline 7.16 If an object appears in more than one view, it should have the same context menu in each. Guideline 7.17 Register all context menus in the view with the platform. Guideline 7.18 Implement an Command Filter for each object type in the view. Guideline 7.19 If a view has support for Cut, Copy, Paste, or any of the global commands, these commands must be executable from the same commands in the window menu bar and toolbar. Guideline 7.20 Persist the state of each view between sessions. Guideline 7.21 Navigation views should support "Link with Editor" on the view menu Perspectives Guideline 8.1 Create a new perspective type for long lived tasks, which involve the performance of smaller, non-modal tasks. Guideline 8.2 If you just want to expose a single view, or two, extend an existing perspective type. Guideline 8.3 The size and position of each view in a perspective should be defined in a reasonable manner, such that the user can resize or move a view if they desire it. When defining the initial layout, it is important to consider the overall flow between the views (and editors) in the perspective. Guideline 8.4 If a perspective has just one part, it may be better suited as a view or editor. Guideline 8.5 If it is undesirable to have an editor area in a perspective, hide it. Do not resize the editor area to the point where it is no longer visible. Guideline 8.6 Populate the window menu bar with commands and command sets which are appropriate to the task orientation of the perspective, and any larger workflow. Guideline 8.7 A new perspective should be opened only if the user explicitly states a desire to do so. In making this statement, the user agrees to leave their old context, and create a new one. Guideline 8.8 If a new perspective is opened as a side effect of another command, the user should be able to turn this behavior off. Guideline 8.9 If a new perspective is opened, it should be opened within the current window, or in a new window, depending on the user preference. Guideline 8.10 The list of shortcuts added to the New, Open Perspective, and Show View menus should be at most 7 plus / minus 2 items. Windows Guideline 9.1 Use an Action Set to contribute actions to the window menu bar and toolbar. Guideline 9.2 Follow the platform lead when distributing actions within an Action Set. Guideline 9.3 Contribute actions to the window menu bar first, and then to the window toolbar if they will be frequently used. Guideline 9.4 Define each action set with a specific task in mind. Guideline 9.5 An action set should contain the smallest possible semantic chunking of actions. Avoid the temptation to provide only one action set for an entire plug-in. Guideline 9.6 Use an action set to share a set of actions which are useful in two or more views or editors. Guideline 9.7 Let the user control the visible action sets. Don't try to control it for them. Guideline 9.8 "Open Object" actions must appear in the Navigate pulldown menu of the window. Guideline 9.9 Always use the global status bar to display status related messages. Properties Guideline 10.1 Use the Properties view to edit the properties of an object when quick access is important, and you will switch quickly from object to object. Guideline 10.2 Use a Properties Dialog to edit the properties of an object which are expensive to calculate. Guideline 10.3 Use a Properties Dialog to edit the properties of an object which contain complex relationships to one another. Guideline 10.4 Properties Dialog should contain the superset of items shown in the Properties view. Widgets Guideline 11.1 For Tree and Table widgets that have a checkbox associated with a cell item, 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. Standard Components Guideline 12.1 If appropriate, add actions to standard components of Eclipse using the plug-in registry. Guideline 12.2 If you subclass or copy any of the standard components, always carry over the standard components' characteristics. The Navigator View Guideline 13.1 Add actions to the Navigator View menu, toolbar, and context menu using the plug-in registry. Guideline 13.2 Use the attributes defined in IResourceActionFilter.java and IProjectActionFilter.java to control the visibility of context menu actions in the Navigator. Guideline 13.3 Use a "Navigate -> Show In Navigator" command in each view, to link resources back to the Navigator. The Tasks View Guideline 14.1 Add markers (tasks, errors and warnings) to the Tasks view using the Marker Manager services from the Core Resources Management plugin. Guideline 14.2 The description text of each marker should be short and concise, so that it will fit in the status line of Eclipse. Guideline 14.3 Add actions to the Tasks view menu, toolbar, and context menu using the plug-in registry. Guideline 14.4 Use the attributes defined in IMarkerActionFilter.java to control the visibility of context menu actions in the Tasks view. Guideline 14.5 Support F1 keyboard command and link it to an infopop that gives a detailed description of the selected item in the Task view. The Preference Dialog Guideline 15.1 Global options should be exposed within the Preferences Dialog. Guideline 15.2 Expose the preferences for a particular view, editor or window in the view itself, via a menu or tool item. Guideline 15.3 Start out with a single preference page. Then evolve to more if you need to. Guideline 15.4 If you create a preference group, use the root page for frequently used preferences, or those preferences which have wide spread effect. Specialize within the sub pages. The root preference page should not be blank. Guideline 15.5 Attempt to integrate plug-in preferences, wizards, and views into existing categories for a new plug-in first, before considering the creation of a new category. Flat Look Design Guideline 16.1 Use Flat Look design for user scenarios that involves extensive property and configuration editing. Guideline 16.2 Have the core sections on the overview page expanded, and provide a "Home" icon on other pages to take users back to the overview page. Guideline 16.3 Use grouping elements corresponding to tabs in the Flat Look content editor for the organization of the tree view in outline view. The Tao of Resource Guideline 17.1 Expose the resource for resource equivalent model objects using an IContributorResourceAdapter. Accessibility Guideline 18.1 All of the features provided by a tool should be accessible using a mouse or the keyboard. Glossary Command A command, which is invoked by a user to carry out some specific functions, may appear as an item in a menu, or an item in a toolbar. In reflection of this, it has attributes for the menu or tool item label, tooltip, and image. As a plug-in developer, you can contribute commands to the window menu bar and toolbar, or to individual views and editors. Contribution to the window is performed using 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. Bookmarks View A view used to browse the bookmarks in the workbench. Editor An editor is a visual component within a workbench page. It is typically used to edit or browse a document or input object. The input is identified using an IEditorInput. Modifications made in an editor part follow an open-save-close lifecycle model (in contrast to a view part, where modifications are saved to the workbench immediately). File An object in the workspace, analogous to files in the file system. Folder A container for files in the workspace. Navigator View A view used to browse the files in the workspace Outline View A view, commonly used to view the outline of the active editor. Perspective A perspective is a visual container for a set of views and editors (parts). These parts exist wholly within the perspective and are not shared. A perspective is also like a page within a book. It exists within a window along with any number of other perspectives and, like a page within a book, only one perspective is visible at any time. Platform A generic framework for the integration of tools. Preferences A Preference Page is used to edit the preferences for a feature in the platform. Project A group of files and folders within the workspace. Each project maps to a corresponding user specified directory in the file system. Properties View A view, typically used to browse the properties for an object in the active editor or view. Properties Dialog A dialog for editing the properties of an object. Property Page A page within a Properties Dialog. Resource The generic name for projects, folders and files. Tasks View A view used to browse the tasks, errors, and warnings within the workspace. View A view is a visual component within a workbench page. It is typically used to navigate a hierarchy of information (like the workspace), open an editor, or display properties for the active editor. Modifications made in a view are saved immediately (in contrast to an editor part, which conforms to a more elaborate open-save-close lifecycle). Wizard A Wizard is typically used to create new resources, import resources, or export resources. Workbench The Workbench provides the user interface structure for Eclipse. The purpose of the Workbench is to facilitate the seamless integration of tools. These tools contribute to extension points defined by the Workbench. The Workbench is responsible for the presentation and coordination of the user interface. Workspace The various tools plugged in to the Eclipse Platform operate on regular files in the user's workspace. The workspace consists of one or more top level projects, where each project maps to a corresponding user specified directory in the file system. Each project contains a collection of folders and files. Acknowledgement Screenshots contributed to Eclipse.org and used in this document, originate from plugins released or under development by the following teams: Java Development Tooling, Eclipse Subproject WebSphere® Studio Application Developer, IBM Corporation Rational XDE Professional, IBM Corporation. By agreeing to share selected elements of their user interface designs (both positive and negative), we feel that these teams have helped make the UI guidelines stronger. Revision History This covers the more significant changes to the guidelines since Version 1.0: Added General UI Principles : "Decorators" subsection "Visual Design" section covers consistency, design and implementation issues for UI graphics Component Development : "Widgets" subsection describes some of the recommended designs for Standard Windows Toolkit (SWT) widgets "Flat Look Design" section for user scenarios that involve extensive property and configuration editing "Best Practices" section provides examples of best practices for designing and implementing some common user interactions Removed Component Development : Perspectives : Opening a perspective in code - Guideline "Consider replacing the perspective type before you open a new perspective" has been removed Component Development : Windows : Actions - "Open Application" has been removed Modified Anything referred to as an "action" in Version 1.0 of the guidelines has been changed to "command" in Version 2.1 of the guidelines The full guideline document has been reformatted and the graphical presentation has been updated Eclipse v3.x UI Guidelines Updates We have created a section for hosting the drafts of ongoing Eclipse v3.x UI guidelines (Best Practices) updates. Go to Eclipse UI Best Practices v3.x updates Version 2.1 February 2004 Copyright© 2001 - 2004 International Business Machine Corporation. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.