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 "Talk:User Interface Guidelines"

m (UI Forms)
 
(29 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 +
{{Warning|The UI guidelines have been migrated to https://github.com/eclipse-platform/ui-best-practices}}
 +
 +
 +
== Comments & Updates ==
 +
 +
=== Tooltips and Infotips ===
 +
 +
Question regarding 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."
 +
 +
Microsoft distinguishes tooltips (very short labels for icons) from [https://msdn.microsoft.com/en-us/library/windows/desktop/dn742443(v=vs.85).aspx) infotips] (more extensive descriptions of an already labeled action) even though they use the same UI widget.
 +
 +
Should Eclipse do similarly? The punctuation and case guidelines seem to make more sense for a tooltip than an Infotip.
 +
 +
=== Titlebar icons ===
 +
 
Question regarding 1.5.5.3.2 "Titlebar icons": Why are we documenting the behavior of a widget on a specific platform with specific theme enabled? These values are not guaranteed even just looking at windows alone. (Randy Hudson)
 
Question regarding 1.5.5.3.2 "Titlebar icons": Why are we documenting the behavior of a widget on a specific platform with specific theme enabled? These values are not guaranteed even just looking at windows alone. (Randy Hudson)
  
 +
 +
=== Messages ===
 
Somewhere around guideline 1.8/1.9 should mention guidelines for translated messages. In particular, when to use single quote and double quote (see discussion in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=147075 bug 147075]).  It should also suggest that error messages not go into too much implementation detail or use technical language that end users will not typically understand. Also, I think the details of guideline 1.9 are incorrect.  We never show details such as plug-in id and version in error dialogs.  Perhaps this intended to say that errors in the '''log file''' should have those details (John Arthorne)
 
Somewhere around guideline 1.8/1.9 should mention guidelines for translated messages. In particular, when to use single quote and double quote (see discussion in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=147075 bug 147075]).  It should also suggest that error messages not go into too much implementation detail or use technical language that end users will not typically understand. Also, I think the details of guideline 1.9 are incorrect.  We never show details such as plug-in id and version in error dialogs.  Perhaps this intended to say that errors in the '''log file''' should have those details (John Arthorne)
  
 
I think the details in 1.9 are correct, it is a ready for websphere guideline I seem to remember. It does however only refer to programming errors and not user errors. Maybe the text should be a bit more explicit about what is meant by programming errors. If your application is just about to die with a null pointer exception it should tell the user exactly what piece of code did it. (Phill Perryman)  
 
I think the details in 1.9 are correct, it is a ready for websphere guideline I seem to remember. It does however only refer to programming errors and not user errors. Maybe the text should be a bit more explicit about what is meant by programming errors. If your application is just about to die with a null pointer exception it should tell the user exactly what piece of code did it. (Phill Perryman)  
  
 +
 +
=== Typo ===
 
In the past commands were called actions and someone has done a global replace of action for command but not changed the "an" to an "a" so it now reads "an command" throughout the article instead of "a command". (Phill Perryman)
 
In the past commands were called actions and someone has done a global replace of action for command but not changed the "an" to an "a" so it now reads "an command" throughout the article instead of "a command". (Phill Perryman)
  
 +
''Fixed in 2.1 document.''
 +
 +
 +
=== UI Graphic resources ===
 
Can you please include the colour palette file or links to them. Re-creating the full 256 colour palette by hand would be difficut to ay the least. Also my Eclipse (3.2) uses more than 2 colours for disabled icons and I can's seem to see any non colour enabled icons. Likewise your screen captures show non colour icons so do not look like the 3.2 Eclipse. Don't forget a link to the palette in 2.9 as well. Not sure what 2.15 means I only see colour and disabled icons.(Phill Perryman)
 
Can you please include the colour palette file or links to them. Re-creating the full 256 colour palette by hand would be difficut to ay the least. Also my Eclipse (3.2) uses more than 2 colours for disabled icons and I can's seem to see any non colour enabled icons. Likewise your screen captures show non colour icons so do not look like the 3.2 Eclipse. Don't forget a link to the palette in 2.9 as well. Not sure what 2.15 means I only see colour and disabled icons.(Phill Perryman)
  
 +
''Added to 3.x document. See UI Graphics section.''
 +
 +
In general, some images are not visible.(Lee Sanghoon)
 +
 +
In [[User_Interface_Guidelines#Style_.26_Design]] it says 'Eclipse supports 24 bit color depth, which means that colors used to create UI graphics can come from outside the defined 8 bit, or 256 color Eclipse-style palette.' but the palette image [[Image:Des_colour_pal.png]] has 33*10 = 330 entries. Please can someone explain.
 +
 +
=== UI Text : Colons ===
 
Guideline 1.6 (sentence style) it does not mention that eclipse almost always adds a colon to the end of its labels when they prefix a control such as text or combo and that postfix labels have no terminator.(Phill Perryman)
 
Guideline 1.6 (sentence style) it does not mention that eclipse almost always adds a colon to the end of its labels when they prefix a control such as text or combo and that postfix labels have no terminator.(Phill Perryman)
  
== Error Handling (1.8) ==
+
 
 +
=== Error Handling (1.8) ===
  
 
The error messages are often not helpful. Some guidelines for actually writing error messages would improve consistency and usability. For example:
 
The error messages are often not helpful. Some guidelines for actually writing error messages would improve consistency and usability. For example:
Line 30: Line 61:
 
Guidelines 3.4 and 3.5 contradict each other so should probably be a single recommendation with 3.4 having a providing... clause at the end.(Phill Perryman)
 
Guidelines 3.4 and 3.5 contradict each other so should probably be a single recommendation with 3.4 having a providing... clause at the end.(Phill Perryman)
  
==  Limit Context Menus ==
+
 
 +
===  Limit Context Menus ===
  
 
This section of the guidelines makes sense...until you try realize that the context menus are not really under control of any one author or the user.  For editors at least, these menus are built up from the editor code itself and plugin contributions.  The plugin contributions are to each editor individually: the final set of menu items depends upon the relative age of the editor and plugins that contribute menu items.  A new editor will have the menus designed by the editor author; over time plugin developers may realize the new editor exists and add their contributions.  The poor user gets context menus which are inconsistent between file types and across time as plugins are added or updated.   
 
This section of the guidelines makes sense...until you try realize that the context menus are not really under control of any one author or the user.  For editors at least, these menus are built up from the editor code itself and plugin contributions.  The plugin contributions are to each editor individually: the final set of menu items depends upon the relative age of the editor and plugins that contribute menu items.  A new editor will have the menus designed by the editor author; over time plugin developers may realize the new editor exists and add their contributions.  The poor user gets context menus which are inconsistent between file types and across time as plugins are added or updated.   
Line 36: Line 68:
 
I think the control over context menus should be given to users, not editor or plugin authors. Users should be able to select a set of global (all file types) entries and configure each context for type-specific entries. If the configurations could be exported and imported as text, users could share and eventually a few best-practice configurations would emerge. --[[User:Johnjbarton.johnjbarton.com|Johnjbarton.johnjbarton.com]] 20:54, 20 October 2006 (EDT)
 
I think the control over context menus should be given to users, not editor or plugin authors. Users should be able to select a set of global (all file types) entries and configure each context for type-specific entries. If the configurations could be exported and imported as text, users could share and eventually a few best-practice configurations would emerge. --[[User:Johnjbarton.johnjbarton.com|Johnjbarton.johnjbarton.com]] 20:54, 20 October 2006 (EDT)
  
== Links and Buttons ==
+
 
 +
===  Capitalization ===
 +
Trying to move this topic to new format.
 +
Draft is [http://wiki.eclipse.org/index.php/Talk:Capitalization here]
 +
 
 +
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=183790 Bug 183790] has been created to track this.
 +
 
 +
 
 +
===  General UI Guidelines ===
 +
Add links to the cited platform-specific UI Guidelines:
 +
* [http://www.microsoft.com/downloads/details.aspx?FamilyID=b996e1e7-a83a-4cae-936b-2a9d94b11bc5&displaylang=en Windows User Experience Guidelines]
 +
* [http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGIntro/XHIGIntro.html Apple Human Interface Guidelines]
 +
* [http://developer.gnome.org/projects/gup/hig/ GNOME Human Interface Guidelines]
 +
* [http://java.sun.com/products/jlf/index.html Java Look and Feel Design Guidelines]
 +
 
 +
== Work In Progress ==
 +
=== Links and Buttons ===
  
 
Given the increasing use of hyperlinks in Eclipse, I was wondering if it would be appropriate to establish some guidelines as to their use.  There seems to be two general uses, as traditional hyperlinks to navigate to a different location (for example, the File Assocations, Content Types and Appearance links on the General->Editors preference page) and to open dialogs/wizards (for example, the Configure Project Specific Settings... link on the Java->Compiler preference page).  My specific area of confusion lies in the latter use case, its not clear to me under what circumstances I should be using a button and under what circumstances I should be using a hyperlink.  If you could provide a guideline to go by, that'd be greatly appreciated.
 
Given the increasing use of hyperlinks in Eclipse, I was wondering if it would be appropriate to establish some guidelines as to their use.  There seems to be two general uses, as traditional hyperlinks to navigate to a different location (for example, the File Assocations, Content Types and Appearance links on the General->Editors preference page) and to open dialogs/wizards (for example, the Configure Project Specific Settings... link on the Java->Compiler preference page).  My specific area of confusion lies in the latter use case, its not clear to me under what circumstances I should be using a button and under what circumstances I should be using a hyperlink.  If you could provide a guideline to go by, that'd be greatly appreciated.
  
(from David.Brandow@sybase.com)
+
from David.Brandow@sybase.com)
  
  
Line 46: Line 94:
 
* Case 1: Quick navigational links within preferences (or same dialog)
 
* Case 1: Quick navigational links within preferences (or same dialog)
 
* Case 2: Links that open other wizards or dialogs
 
* Case 2: Links that open other wizards or dialogs
<br/>
+
 
 +
The working page is [[Links and Buttons | here]].
 +
 
 +
''In Progress.''
 +
 
 +
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=180282 Bug 180282] has been created to track this.
 +
 
 
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 08:43, 9 February 2007 (EST)
 
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 08:43, 9 February 2007 (EST)
  
== Properties View ==
+
 
 +
=== Properties View ===
  
 
Document best practices for the Properties View in Eclipse. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=173935 bug 173935] has been created to track this.
 
Document best practices for the Properties View in Eclipse. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=173935 bug 173935] has been created to track this.
  
Here's the link to the [http://wiki.eclipse.org/index.php/UI_Best_Practices_v3.x#Properties_View working draft]
+
Here's the link to the [http://wiki.eclipse.org/index.php/UI_Best_Practices_v3.x#Properties_View working draft].
 +
 
 +
''In Progress.''
  
 
--[[User:Jinli.ca.ibm.com|Jinli.ca.ibm.com]] 17:02, 12 February 2007 (EST)
 
--[[User:Jinli.ca.ibm.com|Jinli.ca.ibm.com]] 17:02, 12 February 2007 (EST)
  
== Common Error Messages ==
+
 
 +
Shouldn't some mention of the traditional view be made?  The tabbed view frequently consumes too much screen space (the current recommend example picture is over 1024 pixels wide) and is only of use when the properties are know at design time.  Some editors, such as for XML, do not know the list of properties until runtime.
 +
--[[User:Nitind.us.ibm.com|Nitind.us.ibm.com]] 09:50, 21 November 2007 (EST)
 +
 
 +
=== Common Error Messages ===
  
 
Use the common structure of error messages to help users diagnose and recover from errors. This will document and leverage the new error message framework in Eclipse v3.3. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=173937 bug 173937] has been created to track this.
 
Use the common structure of error messages to help users diagnose and recover from errors. This will document and leverage the new error message framework in Eclipse v3.3. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=173937 bug 173937] has been created to track this.
  
Here's the link to the [http://wiki.eclipse.org/index.php/UI_Best_Practices_v3.x#Common_Error_Messages working draft]
+
Here's the link to the [http://wiki.eclipse.org/index.php/UI_Best_Practices_v3.x#Common_Error_Messages working draft].
 +
 
 +
''In Progress.''
  
 
--[[User:Jinli.ca.ibm.com|Jinli.ca.ibm.com]] 17:02, 12 February 2007 (EST)
 
--[[User:Jinli.ca.ibm.com|Jinli.ca.ibm.com]] 17:02, 12 February 2007 (EST)
  
== Rich Client Applications ==
+
 
 +
=== Rich Client Applications ===
  
 
Provided guidance specific to RCP applications. Including but not limited to:
 
Provided guidance specific to RCP applications. Including but not limited to:
Line 72: Line 136:
 
* Other OS
 
* Other OS
 
* Design
 
* Design
 +
 +
''Help Wanted.''
 +
 
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 08:03, 27 February 2007 (EST)
 
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 08:03, 27 February 2007 (EST)
  
== UI Forms ==
 
  
Provide guidelines for forms UI.
+
=== UI Forms ===
 +
 
 +
Provide guidelines for forms UI.
 +
 
 +
The working page is [[UI Forms | here]].
 +
 
 +
''In Progress.''
 +
 
 +
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=180272 Bug 180272] has been created to track this.
  
 
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 07:35, 21 March 2007 (EST)
 
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 07:35, 21 March 2007 (EST)
 +
 +
 +
=== Top Ten UI Hit Lists ===
 +
 +
The working page is [[Top Ten Lists Working Page | here]].
 +
 +
''In Progress.''
 +
 +
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=180281 Bug 180281] has been created to track this.
 +
 +
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 08:08, 21 March 2007 (EST)
 +
 +
 +
=== Managing Multiple Instances of a View ===
 +
 +
This item was raised in the March 28 UIWG call.
 +
 +
The working page is [[Managing Multiple Instances of a View | here]].
 +
 +
''Help Wanted.''
 +
 +
[[User:Kpeter.ca.ibm.com|Kpeter.ca.ibm.com]] 13:51, 30 March 2007 (EDT)
 +
 +
[[Category:UI_Guidelines]]
 +
 +
 +
=== Context Menus for graphical editors ===
 +
 +
Provide guidelines for context menus of graphical editors
 +
 +
The working page is [[Context_Menus_for_Graphical_Editors | here]].
 +
 +
''In Progress.''
 +
 +
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=284670 Bug 284670 ] has been created to track this.
 +
 +
[[User:eitan.kurejwowski@sap.com|eitan.kurejwowski@sap.com]] 07:35, 26 July 2009 (EST)

Latest revision as of 06:59, 7 February 2024

Warning2.png
The UI guidelines have been migrated to https://github.com/eclipse-platform/ui-best-practices


Comments & Updates

Tooltips and Infotips

Question regarding 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."

Microsoft distinguishes tooltips (very short labels for icons) from infotips (more extensive descriptions of an already labeled action) even though they use the same UI widget.

Should Eclipse do similarly? The punctuation and case guidelines seem to make more sense for a tooltip than an Infotip.

Titlebar icons

Question regarding 1.5.5.3.2 "Titlebar icons": Why are we documenting the behavior of a widget on a specific platform with specific theme enabled? These values are not guaranteed even just looking at windows alone. (Randy Hudson)


Messages

Somewhere around guideline 1.8/1.9 should mention guidelines for translated messages. In particular, when to use single quote and double quote (see discussion in bug 147075). It should also suggest that error messages not go into too much implementation detail or use technical language that end users will not typically understand. Also, I think the details of guideline 1.9 are incorrect. We never show details such as plug-in id and version in error dialogs. Perhaps this intended to say that errors in the log file should have those details (John Arthorne)

I think the details in 1.9 are correct, it is a ready for websphere guideline I seem to remember. It does however only refer to programming errors and not user errors. Maybe the text should be a bit more explicit about what is meant by programming errors. If your application is just about to die with a null pointer exception it should tell the user exactly what piece of code did it. (Phill Perryman)


Typo

In the past commands were called actions and someone has done a global replace of action for command but not changed the "an" to an "a" so it now reads "an command" throughout the article instead of "a command". (Phill Perryman)

Fixed in 2.1 document.


UI Graphic resources

Can you please include the colour palette file or links to them. Re-creating the full 256 colour palette by hand would be difficut to ay the least. Also my Eclipse (3.2) uses more than 2 colours for disabled icons and I can's seem to see any non colour enabled icons. Likewise your screen captures show non colour icons so do not look like the 3.2 Eclipse. Don't forget a link to the palette in 2.9 as well. Not sure what 2.15 means I only see colour and disabled icons.(Phill Perryman)

Added to 3.x document. See UI Graphics section.

In general, some images are not visible.(Lee Sanghoon)

In User_Interface_Guidelines#Style_.26_Design it says 'Eclipse supports 24 bit color depth, which means that colors used to create UI graphics can come from outside the defined 8 bit, or 256 color Eclipse-style palette.' but the palette image Des colour pal.png has 33*10 = 330 entries. Please can someone explain.

UI Text : Colons

Guideline 1.6 (sentence style) it does not mention that eclipse almost always adds a colon to the end of its labels when they prefix a control such as text or combo and that postfix labels have no terminator.(Phill Perryman)


Error Handling (1.8)

The error messages are often not helpful. Some guidelines for actually writing error messages would improve consistency and usability. For example: Explain when to use a plain message dialog, and when to add details. Is the expandable details section for recovery suggestions, or should it be used for log errors? (In Microsoft error messages, the details are usually very technical details) Messages should say what is wrong and always suggest what can be done to fix it. Error messages should identify the component from which it was issued when the user has to seek additional help - complete failure. Don't blame the user for the error. Write complete sentences.

BAD: You don't have enough memory to perform this action. DETAILS>> Action Aborted BETTER: There is insufficient memory to save this file. Increase the available memory by deleting temporary files or removing unused programs. === Sue Yeshin syeshin@ca.ibm.com

Note on taking screencaptures for the guidelines:

Guideline 5.3, 5.4, 5.5, 5.12 (more).... - These guidelines have screen captures that do not have punctuation after the description or error sentences. When choosing examples, they need to show best practices for all the guidelines. I can help find replacement screen caps. Sue Yeshin syeshin@ca.ibm.com


Guidelines 3.4 and 3.5 contradict each other so should probably be a single recommendation with 3.4 having a providing... clause at the end.(Phill Perryman)


Limit Context Menus

This section of the guidelines makes sense...until you try realize that the context menus are not really under control of any one author or the user. For editors at least, these menus are built up from the editor code itself and plugin contributions. The plugin contributions are to each editor individually: the final set of menu items depends upon the relative age of the editor and plugins that contribute menu items. A new editor will have the menus designed by the editor author; over time plugin developers may realize the new editor exists and add their contributions. The poor user gets context menus which are inconsistent between file types and across time as plugins are added or updated.

I think the control over context menus should be given to users, not editor or plugin authors. Users should be able to select a set of global (all file types) entries and configure each context for type-specific entries. If the configurations could be exported and imported as text, users could share and eventually a few best-practice configurations would emerge. --Johnjbarton.johnjbarton.com 20:54, 20 October 2006 (EDT)


Capitalization

Trying to move this topic to new format. Draft is here

Bug 183790 has been created to track this.


General UI Guidelines

Add links to the cited platform-specific UI Guidelines:

Work In Progress

Links and Buttons

Given the increasing use of hyperlinks in Eclipse, I was wondering if it would be appropriate to establish some guidelines as to their use. There seems to be two general uses, as traditional hyperlinks to navigate to a different location (for example, the File Assocations, Content Types and Appearance links on the General->Editors preference page) and to open dialogs/wizards (for example, the Configure Project Specific Settings... link on the Java->Compiler preference page). My specific area of confusion lies in the latter use case, its not clear to me under what circumstances I should be using a button and under what circumstances I should be using a hyperlink. If you could provide a guideline to go by, that'd be greatly appreciated.

from David.Brandow@sybase.com)


Cases summarized:

  • Case 1: Quick navigational links within preferences (or same dialog)
  • Case 2: Links that open other wizards or dialogs

The working page is here.

In Progress.

Bug 180282 has been created to track this.

Kpeter.ca.ibm.com 08:43, 9 February 2007 (EST)


Properties View

Document best practices for the Properties View in Eclipse. bug 173935 has been created to track this.

Here's the link to the working draft.

In Progress.

--Jinli.ca.ibm.com 17:02, 12 February 2007 (EST)


Shouldn't some mention of the traditional view be made? The tabbed view frequently consumes too much screen space (the current recommend example picture is over 1024 pixels wide) and is only of use when the properties are know at design time. Some editors, such as for XML, do not know the list of properties until runtime. --Nitind.us.ibm.com 09:50, 21 November 2007 (EST)

Common Error Messages

Use the common structure of error messages to help users diagnose and recover from errors. This will document and leverage the new error message framework in Eclipse v3.3. bug 173937 has been created to track this.

Here's the link to the working draft.

In Progress.

--Jinli.ca.ibm.com 17:02, 12 February 2007 (EST)


Rich Client Applications

Provided guidance specific to RCP applications. Including but not limited to:

  • Considerations
  • Initial setup and principles for RCP applications (from a UX perspective)
  • Other OS
  • Design

Help Wanted.

Kpeter.ca.ibm.com 08:03, 27 February 2007 (EST)


UI Forms

Provide guidelines for forms UI.

The working page is here.

In Progress.

Bug 180272 has been created to track this.

Kpeter.ca.ibm.com 07:35, 21 March 2007 (EST)


Top Ten UI Hit Lists

The working page is here.

In Progress.

Bug 180281 has been created to track this.

Kpeter.ca.ibm.com 08:08, 21 March 2007 (EST)


Managing Multiple Instances of a View

This item was raised in the March 28 UIWG call.

The working page is here.

Help Wanted.

Kpeter.ca.ibm.com 13:51, 30 March 2007 (EDT)


Context Menus for graphical editors

Provide guidelines for context menus of graphical editors

The working page is here.

In Progress.

Bug 284670 has been created to track this.

eitan.kurejwowski@sap.com 07:35, 26 July 2009 (EST)

Back to the top