Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Top Ten Lists Working Page"

(Top Ten Eclipse UI Violations)
(Top Ten Eclipse UI Guidelines)
Line 32: Line 32:
 
Ref: http://wiki.eclipse.org/index.php/Platform_UI/Accessibility_Features
 
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
  
 
===== Top Ten Eclipse UI Violations =====
 
===== Top Ten Eclipse UI Violations =====

Revision as of 06:08, 26 March 2007

Starter Set

Top Ten Eclipse UI Guidelines

  1. Use the Eclipse look and feel if extending or plugging into Eclipse
  2. Use common SWT controls to get what SWT offers for cross-platform adaptability and accessibility
  3. Be familiar with APIs for the UIs you are building
  4. Use icons and graphics consistent with the Eclipse style, decorations, states, and quality
  5. Understand the conventions of the OSs you are developing for
  6. Use understandable messages to help people recover from error conditions
  7. Don't initiate dialogs or wizards in an error state
  8. Use quick fix and quick assist mechanisms
  9. Reserve time for "polish"


Top Ten 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 (normal and tabbed)
  7. Assuming more importance than other contributions (see John/Mik comments below)


Additions / Ideas

Top Ten Eclipse UI Guidelines

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

Top Ten Eclipse UI Violations

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


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

Back to the top