Top Ten Lists Working Page

Starter Set

Top Eclipse UI Guidelines

Published list: http://wiki.eclipse.org/UI_Checklist

Views & Editors

1. Put only the most commonly used commands on the view toolbar. Any command on a toolbar must also appear in a menu, either the window menu, context menu or the view menu. (Guideline 7.12)
2. Use the view pulldown menu for commands not tied to selection (Guideline 7.10). Fill the context menu with selection oriented actions. (Guideline 7.13)
3. If a view or 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.9, Guideline 7.19)
4. Modifications of workspace resources made in an editor should follow an open-save-close lifecycle model (Guideline 6.2), whereas modifications made within a view should be saved immediately (Guideline 7.2).
5. Persist the state of each view between sessions (Guideline 7.20).

Wizards & Dialogs

1. Start a wizard with a prompt, not an error message. (Guideline 5.3)
2. Seed the fields within a wizard using the current workbench state. (Guideline 5.4)
3. 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.1)
4. Use a Browse Button whenever an existing object is referenced in a wizard. (Guideline 5.8)

Workbench & Preferences

1. Use Headline style capitalization for menus, tooltip and all titles, including those used for windows, dialogs, tabs, column headings and push buttons (Guideline 1.5). 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 (Guideline 1.6).
2. Follow the visual style established for Eclipse UI graphics (Guideline 2.1). Re-use the color palette (Guideline 2.2) and visual concepts to maintain consistent representation and meaning across Eclipse plug-ins (Guideline 2.3).
3. If you must create a new 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.4)

Top Eclipse UI Violations

1. Low quality graphics or not consistent with the Eclipse style
2. Poorly organized or sized dialogs and wizards
3. Useless dialogs
4. Cryptic error messages
5. Messages with concatenated strings
6. Property pages that don't adhere to platform uses where possible (normal and tabbed)
7. Assuming more importance than other contributions (see John/Mik comments below)
8. Using too many custom colors and fonts
9. Flooding the system with updates
10. Slow updating in the main Thread
11. Adding to the preferences rather than making a choice for the user

Additions / Ideas

Top Ten Eclipse UI Guidelines

[ CANDIDATES, not yet integrated into lists ] Should we mention something about Accessibility in the Good Practices list ?

Raji Akella

Ref: http://wiki.eclipse.org/index.php/Platform_UI/Accessibility_Features

The labeling/layout rules for dialogs and wizards are already part of the existing document, but rarely any dialog gets it right the first time. Maybe the new document can add a dialog checklist, wizard checklist etc...

• Dialog titles should
  • Use headline style capitalization
  • Relate to the action that brought up the dialog ('Apply Patch', 'Package Selection')
  • Be short and unique so they can be referred by in bug reports / documentation
• Control labels should
  • Use sentence style capitalization
  • End with a colon (except for radios) ('Type name:')
  • Offer a mnemonic
• Push buttons should
  • Use correct size (not the default size!)
  • Use mnemonics
  • Use headline style capitalization
  • Use existing terminology 'New...', 'Edit...', 'Remove', 'Import...' where possible
  • Always use '...' when the button opens a new dialog
• Groups
  • Labels should use sentence style capitalization
  • Don't nest groups in groups
• All labels should
  • Use single quotes for all references to element names embedded in text (Properties for 'Test')
  • Show workspace paths as relative paths (no leading '/')
  • Use OS path separators for OS paths
• For dialogs that become visible the first time
  • Always set a focus field
  • Don't show an error until the user made the first modification
• All dialogs should
  • Check that controls are aligned to each other and to the left or right (for example aligned to the wizard title and wizard OK/Cancel button)
  • Make sure the font is set to all controls (taken from the parent composite). Test your dialog with a bigger dialog font
  • Be resizable and remember their size (In particular selection dialogs)
  • Make sure that the controls can also handle bigger sizes (always fill space), and smaller sizes (wrap description labels)
  • Remember previous selections
  • Be opened with the correct parent shell

Martin Aeschlimann

5. Bastardized property pages

You may choose to use friendlier language, but it pains me every time I come across a property pages that don't adhere to what the platform uses (normal or tabbed).

Just a pet-peeve ;)

Chris Aniszczyk

Useless dialogs

(Found on Steve Northover's blog: http://inside-swt.blogspot.com/2007/03/useless-dialog-of-day.html)

Kim Peter

Another one for Violations regarding messages:

Creating messages with concatenated strings. They have the potential for losing their meaning when they get translated.

Raji Akella

[ CANDIDATES, not yet integrated into lists ] My favourite Eclipse-specific UI blooper is:

7. Doesn't play well with others.

A plug-in that assumes it is more important than others, and over-uses global real-estate such as top level toolbars and menu, adds perspective extensions that clutter the menus of other perspectives, insert views into other perspectives, clutters popup menus with excessive object contributions, adds startup hooks to run user jobs on startup, etc. 

John Arthorne

John’s item (7) is on top of my list too and wonder how we could make it more concrete. We should also keep in mind counter examples, e.g. it can be better to add your one view to an existing perspective than to burden the user with a whole other perspective. Here’s my quick pass at a rough guideline for an extension that should play well with the SDK.

• Don’t add more than [0] top-level menus to the menu bar. Use existing menu paths whenever possible.
• Don’t add more than [6] always-visible toolbar items.
• Don’t add more than [3] always-visible object contributions to popup menus.
• Don’t add a new perspective if it only adds a view or two, add a viewShortcut instead

I wonder if Europa projects could try to follow such a guideline and help us refine it in the process.

Mik Kersten

+1 for Johns item (7), here are some more items: Use action/wizard page terminology that works well with other contributions :

• A context menu action called 'Analyze...' is too general. Think about an own sub menu that gives more context
• A wizard page group called 'Data' is too technical

Martin Aeschlimann

• Useless borders/gaps in the form-based editors and especially in Views. Those borders just take screen real estate and fairly unpractical.
• Large data shown in the tree widget based UI without support for quick filtering or search
• Too much useless logging to the platform log (and Error Log view). Recoverable errors should be reported in the UI (i.e. decoration, tooltips, but not popup dialogs)
• Lousy presentation of the progress for background tasks in the Progress view. Watch how progress and completion is reported there.
• Creating custom/new views instead of reusing existing views (especially in the IDE). The good candidates for reusing are: Search, History, Console and Properties. Problems view can be efficiently used with custom markers.

Eugene Kuleshov

8. Using too many custom colors and fonts.

The SDK already ships with 70+ colours and fonts. Adding a new one rather than reusing an existing one makes it even more difficult for the user to set what they need.

One thing I would like to see this group do is come up with a list of 5 or 6 main colors that coule be reused by other components.

9. Flooding the system with updates.

In a listener based system like Eclipse doing a lot of unnecessary updates to your listeners can result in a lot of processing time filtering, especially as many listeners do this quickly so they use the UI Thread.

10. Updating in the UI Thread.

This is the single most common UI performance problem because plug-ins tend to do a lot of processing as a result of events from SWT or the workbench which are generally all of the UI Thread.

Some ways to prevent this

• Process using a job and update with a UIJob. Unless you really need to block the UI while you update you can process in a Job which is never on the UIThread and refresh the UI by posting a UIJob when you are done. WorkbnechJob is even better for this as they don't run when the workbench is shutting down.
• Use IProgressService#busyCursorWhile. This brings up a busy cursor after 200ms and a progress dialog after 800 ms. This way the user gets some feedback that you are blocking the UI.

11. Cluttering the preferences dialog

See also UI Guidelines/Preferences. The preferences dialog has grown a lot over time, and has a huge number of entries when you add a couple of other Europa projects to your install. We are approaching a situation where normal users do not use the preferences dialog at all because they are overwhelmed by the number of things they can adjust. Plug-ins should try to make decisions for their users instead of placing the burden of those decisions on the users by making everything adjustable in the preferences.