Bug 508819: Define proper API for hover/info color constantsI20171012-2000I20171011-2000

(platform.ui)

I previously defined a "HOVER" color to allow information planes like
javadoc, problem views etc.. to be styled and have proper colors on
dark theme. However, later non-hover controls started using the color
(e.g javadoc part), and "HOVER" turned out to be a bad name for the
color.
In this patch I'm deprecating the HOVER_ color without breaking
backwards support, and instead I'm introducing "INFORMATION_*" color.

Test:
- Apply patch, launch child Eclipse.
- Try dark theme.
- Inspect Color preference

Results:
- Colors of Javadoc Hover on Dark theme work as before.
- Information Colors in preference page look ok. Description is set.
  Javadoc background/foreground have correct colors. DefaultsTo
  buttons and "editDefault" are grayed out, so old deprecated color
  cannot be edited by javadoc colors (this was fixed in 516533).
  This means that there are no "dead" colors that are uneditable.
- Javadoc colors do not mention "deprecated' anywhere, so deprecation
  is transparent to users.

Notes:
- hovering over "Javadoc" does not leak any notices of deprecation
to user. Only developers will see the 'deprecation' note, users will
be unaware.

- Once this patch is merged, I will update JDT not to reference HOVER_
anymore.

I can't think of a better solution to deprecating a color and haven't
found other examples to copy from. If someone has alternative
suggestions, please let me know.

I tested that JDT does not break with this change. Javadoc hovers are
present as before.

Patch notes:

Patch Set 1,2:
- Implementing INFORMATION_ color ID instead of "HOVER_", because
the colors are used in non-hover context.

Patch Set 3:
- Implemented solution with backwards compatibility.
- Introduced INFORMATION_* colors.
- Made old HOVER_* colors not-visible to the user (isEditable=false)

Patch Set 4:
- Moved deprecated note from label into description, and set labels to:
  "Hover * color".
  This way the javadoc colors don't mention deprecation in user
interface, but a developer who looks at the color in the code will
notice the description that links to the proper color. (See attached
screenshot 'javadoc default label').
  AFIK the user now never sees anything 'deprecated' related.

Patch Set 7:
- Rebased/updated.

Change-Id: I76670ce5b1ec896d8f153ae0d9d161ae38c51ad2
Signed-off-by: Leo Ufimtsev <lufimtse@redhat.com>

5 files changed, 61 insertions, 21 deletions

diff --git a/bundles/org.eclipse.jface/src/org/eclipse/jface/preference/JFacePreferences.java b/bundles/org.eclipse.jface/src/org/eclipse/jface/preference/JFacePreferences.java
index f1b6e024194..5622c462e86 100644
--- a/bundles/org.eclipse.jface/src/org/eclipse/jface/preference/JFacePreferences.java
+++ b/bundles/org.eclipse.jface/src/org/eclipse/jface/preference/JFacePreferences.java
@@ -74,7 +74,21 @@ public final class JFacePreferences {
 	 */
 	public static final String CONTENT_ASSIST_FOREGROUND_COLOR = "CONTENT_ASSIST_FOREGROUND_COLOR"; //$NON-NLS-1$
 
+	/**
+	 * The color used for the background of controls that provide information
+	 * for reading. E.g. Hover boxes with information like javadoc or view parts.
+	 *
+	 * @since 3.14
+	 */
+	public static final String INFORMATION_BACKGROUND_COLOR = "org.eclipse.ui.workbench.INFORMATION_BACKGROUND"; //$NON-NLS-1$
 
+	/**
+	 * The color used for text for controls that provide information for
+	 * reading. E.g. Hover boxes with information like javadoc or view parts.
+	 *
+	 * @since 3.14
+	 */
+	public static final String INFORMATION_FOREGROUND_COLOR = "org.eclipse.ui.workbench.INFORMATION_FOREGROUND"; //$NON-NLS-1$
 
 	private static IPreferenceStore preferenceStore;
 
diff --git a/bundles/org.eclipse.ui.themes/css/dark/e4-dark_preferencestyle.css b/bundles/org.eclipse.ui.themes/css/dark/e4-dark_preferencestyle.css
index c029a9ed119..3987fa0c371 100644
--- a/bundles/org.eclipse.ui.themes/css/dark/e4-dark_preferencestyle.css
+++ b/bundles/org.eclipse.ui.themes/css/dark/e4-dark_preferencestyle.css
@@ -55,6 +55,8 @@ IEclipsePreferences#org-eclipse-ui-workbench:org-eclipse-ui-themes { /* pseudo a
 		'CONFLICTING_COLOR=240,15,66'
 		'CONTENT_ASSIST_BACKGROUND_COLOR=52,57,61'
 		'CONTENT_ASSIST_FOREGROUND_COLOR=238,238,238'
+		'org.eclipse.ui.workbench.INFORMATION_BACKGROUND=52,57,61'
+		'org.eclipse.ui.workbench.INFORMATION_FOREGROUND=238,238,238'
 		'org.eclipse.ui.workbench.HOVER_BACKGROUND=52,57,61'
 		'org.eclipse.ui.workbench.HOVER_FOREGROUND=238,238,238'
 		'ERROR_COLOR=247,68,117'
diff --git a/bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/themes/RGBInfoColorFactory.java b/bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/themes/RGBInfoColorFactory.java
index 9e6ba9c4943..38a725c49c0 100644
--- a/bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/themes/RGBInfoColorFactory.java
+++ b/bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/themes/RGBInfoColorFactory.java
@@ -10,8 +10,12 @@ import org.eclipse.ui.themes.IColorFactory;
 
 /**
  * Used in org.eclipse.ui.themes extension point of the org.eclipse.ui plug-in
- * for the color definition org.eclipse.ui.workbench.HOVER_BACKGROUND and
- * org.eclipse.ui.workbench.HOVER_FOREGROUND
+ * for the color definition of elements that provide text information.
+ *
+ * This provides colors that are easily readable across different platforms.
+ * <br>
+ * Win32 & Cocoa: Yellow background & black text. (COLOR_INFO_*) <br>
+ * GTK: White background and black text. (COLOR_LIST_*)
  */
 public class RGBInfoColorFactory implements IColorFactory, IExecutableExtension {
 	String color;
diff --git a/bundles/org.eclipse.ui/plugin.properties b/bundles/org.eclipse.ui/plugin.properties
index bf53fe8fec6..1e7c5ed9500 100644
--- a/bundles/org.eclipse.ui/plugin.properties
+++ b/bundles/org.eclipse.ui/plugin.properties
@@ -323,8 +323,15 @@ Color.inactiveTabBGEnd=Inactive part background end
 Color.inactiveTabBGStartDesc=The first color used for inactive view and editor title gradients.  This color is also used for active editors that do not have focus.
 Color.inactiveTabBGEndDesc=The second color used for inactive view and editor title gradients.  This color is also used for the view menu background.
 
-Color.infoBackground=Information background color
-Color.infoForeground=Information text color
+Color.informationBackground=Information background color
+Color.informationBackgroundDesc=The color used for background of controls that provide information
+Color.informationForeground=Information text color
+Color.informationForegroundDesc=The color used for text of controls that provide information
+Color.hoverBackgroundDeprecated=Hoverbox background color
+Color.hoverBackgroundDeprecatedDesc=Hover background Color is deprecated. Use org.eclipse.ui.workbench.INFORMATION_BACKGROUND instead.
+Color.hoverForegroundDeprecated=Hoverbox text Color
+Color.hoverForegroundDeprecatedDesc=Hover foreground Color is deprecated. Use org.eclipse.ui.workbench.INFORMATION_FOREGROUND instead.
+
 Color.errorText=Error text color
 Color.errorTextDesc=Color used to show error messages.
 Color.hyperlinkText=Hyperlink text color
diff --git a/bundles/org.eclipse.ui/plugin.xml b/bundles/org.eclipse.ui/plugin.xml
index ecf62348b50..406e910aa6c 100644
--- a/bundles/org.eclipse.ui/plugin.xml
+++ b/bundles/org.eclipse.ui/plugin.xml
@@ -1900,30 +1900,43 @@
       		name="org.eclipse.ui.workbench.ACTIVE_TAB_HIGHLIGHT" value="false">
 		 </data>
       </theme>
+
       <colorDefinition
             categoryId="org.eclipse.ui.workbenchMisc"
-            id="org.eclipse.ui.workbench.HOVER_BACKGROUND"
-            label="%Color.infoBackground">
-            <colorFactory
-               class="org.eclipse.ui.internal.themes.RGBInfoColorFactory"
-               plugin="org.eclipse.ui">
-               <parameter
-                      name="color"
-                      value="background">
-                </parameter>
+            id="org.eclipse.ui.workbench.INFORMATION_BACKGROUND"
+            label="%Color.informationBackground">
+            <description> %Color.informationBackgroundDesc</description>
+            <colorFactory class="org.eclipse.ui.internal.themes.RGBInfoColorFactory" plugin="org.eclipse.ui">
+               <parameter name="color" value="background"> </parameter>
             </colorFactory>
       </colorDefinition>
       <colorDefinition
             categoryId="org.eclipse.ui.workbenchMisc"
+            id="org.eclipse.ui.workbench.INFORMATION_FOREGROUND"
+            label="%Color.informationForeground">
+            <description> %Color.informationForegroundDesc</description>
+            <colorFactory class="org.eclipse.ui.internal.themes.RGBInfoColorFactory" plugin="org.eclipse.ui">
+               <parameter name="color" value="foreground"></parameter>
+            </colorFactory>
+      </colorDefinition>
+     <colorDefinition
+            categoryId="org.eclipse.ui.workbenchMisc"
+            id="org.eclipse.ui.workbench.HOVER_BACKGROUND"
+            isEditable="false"
+            label="%Color.hoverBackgroundDeprecated">
+            <description> %Color.hoverBackgroundDeprecatedDesc</description>
+            <colorFactory class="org.eclipse.ui.internal.themes.RGBInfoColorFactory" plugin="org.eclipse.ui">
+               <parameter name="color" value="background"></parameter>
+            </colorFactory>
+      </colorDefinition>
+	 <colorDefinition
+            categoryId="org.eclipse.ui.workbenchMisc"
             id="org.eclipse.ui.workbench.HOVER_FOREGROUND"
-            label="%Color.infoForeground">
-            <colorFactory
-               class="org.eclipse.ui.internal.themes.RGBInfoColorFactory"
-               plugin="org.eclipse.ui">
-               <parameter
-                      name="color"
-                      value="foreground">
-                </parameter>
+            isEditable="false"
+            label="%Color.hoverForegroundDeprecated">
+            <description> %Color.hoverForegroundDeprecatedDesc</description>
+            <colorFactory class="org.eclipse.ui.internal.themes.RGBInfoColorFactory" plugin="org.eclipse.ui">
+               <parameter name="color" value="foreground"></parameter>
             </colorFactory>
       </colorDefinition>
       <theme