DESCRIPTION

Bug 501742: Default Javadoc text and background color should use colors
consistent with Java editor background/foreground. 

Patch 1/2:
Implementation of IColorFactory (See Solution 2 of bug).
Such that Javadoc (in *.jdt.ui) can use this factory
to set background/foreground color that looks consistent with 
regards to the rest of the UI.

Patch 2 will be in *.jdt.ui.

[update patch set 4]
Updating MANIFEST.MF and pom.xml version to 3.110, because external
class in *.jdt.ui will use the new factory. See patch 2/2 in bug.

Change-Id: I97b6912a4c3b6533f766230ff7180eb1a68c9f7b
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=501742
Signed-off-by: Natalia Golden xxx@xxx.xxx


COMMENTS

author: Natalia Golden
date: 2016-10-04 15:12:11.000000000

Uploaded patch set 4.

-------------------------------------
author: Natalia Golden
date: 2016-10-04 15:13:00.000000000

Patch Set 4:

> How is the CSS setting related to this change? The color factory is
 > a nice idea but should this not be placed in SWT? 

@ Lars:
Sorry, I somehow didn't see your comment.

i) The CSS change is for the dark theme. Without the CSS change, the Javadoc doesn't look proper on the Gtk dark theme. (Doesn't 'quite' match the look). I basically copied what CONTENT_ASSIST_BACKGROUND_COLOR did to style Javadoc when the user switches to dark theme.

ii) I can't think of a way to fix this on the SWT level without breaking things like tooltips. Some users want black tooltips with white text, to match the native OS tooltips. If I change SWT, we might get complaints. (Unless you have some idea/suggestion? Thoughts?).


 > I also dislike
 > the hard-code aspect, maybe this could be defaulted and make
 > stylable from the outside, via the CSS engine?
iii) I don't quite understand this bit. Do you mean hard-code aspect in dark_preferencestyle.css or in the color factory?
a) The .css coding is for the darktheme, bunch of stuff is hard-coded there for better dark-theme looks (e.g the method outline). Why would that be an issue?
b) The factory doesn't really interfere with CSS. I.e it can produce one thing, but then CSS can override it. So unless I'm missing something, it's not really hard coding it. 
Can you explain? If feel like I'm missing something.


@ Sergey,
iv) Oh, thanks I didn't know that version was in both pom.xml and MANIFEST.MF.

v)
 > Wasn't the version already incremented by commit a72dda9b94f07f1c95d7f51f9380a17eec581c88 ?
 Hmmm, I may be wrong, but shouldn't the minor segment version be incremented for every "Externally visible" change?
 http://wiki.eclipse.org/Version_Numbering#When_to_change_the_minor_segment
 This would be such a change, no?
 My line of thought is that *.jdt.ui will not function between a72dda9b94f07f1c95d7f51f9380a17eec581c88 and this commit,
 thus the increment. Am I missing something?
 Or do we only change the minor-segment once per the release of a plug or something like that?
 Can you elaborate?

-------------------------------------
author: Zaid Mosley
date: 2016-10-04 15:26:44.000000000

Patch Set 4:

Please do not merge this yet. I have a detailed look this week.

-------------------------------------
author: Brenden Conley
date: 2016-10-04 15:48:58.000000000

Patch Set 4:

Build Started https://hudson.eclipse.org/platform/job/eclipse.platform.ui-Gerrit/10770/

-------------------------------------
author: Brenden Conley
date: 2016-10-04 16:10:13.000000000

Patch Set 4: Verified-1

Build Failed 

https://hudson.eclipse.org/platform/job/eclipse.platform.ui-Gerrit/10770/ : FAILURE

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 06:16:27.000000000

Patch Set 4: Code-Review-1

I think this patch is a mixture of tooltip and Javadoc popup.

I suggest to solve the Javadoc popup in the normal theme with a preference setting in e4_default_gtk.css. With the adjustments Leo did in the other bugs, this works fine:

IEclipsePreferences#org-eclipse-ui-workLeon Ochoach {
	preferences:
		'org.eclipse.jdt.ui.Javadoc.backgroundColor=255,0,0'
		'org.eclipse.jdt.ui.Javadoc.foregroundColor=0,0,255'
}

Of course we should use better colors. ;-) And the tooltip color should be solved by a separate bug / Gerrit.

-------------------------------------
author: Erick Ross
date: 2016-10-05 16:21:12.000000000

Patch Set 4:

> I think this patch is a mixture of tooltip and Javadoc popup.
 > 
 > I suggest to solve the Javadoc popup in the normal theme with a
 > preference setting in e4_default_gtk.css. With the adjustments Leo
 > did in the other bugs, this works fine:
 > 
 > IEclipsePreferences#org-eclipse-ui-workLeon Ochoach {
 > preferences:
 > 'org.eclipse.jdt.ui.Javadoc.backgroundColor=255,0,0'
 > 'org.eclipse.jdt.ui.Javadoc.foregroundColor=0,0,255'
 > }
 > 
 > Of course we should use better colors. ;-) And the tooltip color
 > should be solved by a separate bug / Gerrit.

What about people running with theming engine disabled? Some kind of color factory is needed for this case or there will still be black javadoc view in this case.

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 18:45:30.000000000

Patch Set 4:

> What about people running with theming engine disabled? Some kind of color factory is needed for this case or there will still be black javadoc view in this case.

The preference solution requires CSS to be used. I suggest to solve this first with CSS (as this is anyway required for the dark theme) and continue to investigate. I personally would prefer that SWT returns on GTK the correct solors.

-------------------------------------
author: Natalia Golden
date: 2016-10-05 18:57:28.000000000

Patch Set 4: Code-Review+1

> I suggest to solve the Javadoc popup in the normal theme with a
 > preference setting in e4_default_gtk.css. With the adjustments Leo
 > did in the other bugs, this works fine:
 > 
 > IEclipsePreferences#org-eclipse-ui-workLeon Ochoach {
 > preferences:
 > 'org.eclipse.jdt.ui.Javadoc.backgroundColor=255,0,0'
 > 'org.eclipse.jdt.ui.Javadoc.foregroundColor=0,0,255'
 > }

Thank you for reviewing the patch. It's an interesting suggestion, I had the same thing in mind initially, but there are issues that come to mind:

1) As Alex pointed out, the above solution doesn't work if Preference->General->Appearance->"Enable theming" is turned off.

2) Further, this solution hard-codes a color, but the underlying system colors might differ, which would lead to an inconsistent look between Javadoc and the editor, thus not fully fixing the bug.

3) Further, I think it's fine to hard code colors in the dark theme because it's a special case, but we should try to avoid CSS'ign too much for regular gtk. The reason for this is that I know that the dark theme actually introduces bugs into the U.I, (ex Bug 499515). Also, I know that currently there are performance issues on Wayland with clicking that could potentially be related to the theming engine (I need to investigate this further, but just a hunch)... 

That is the reason why I took the extra time to implement the IColorFactory. It's a bit of a round-about way of solving the problem, but it does solve the problem and in the future it can be re-used and extended for other things without having to hand-code everything into the CSS engine (For example the "Suggested solutions" pop-up comes to mind).

Based on the problems with CSS hard-coding, I suggest to move forward with the IColorFactory. (Unless you can think of some way to address the problems or have another suggestion in mind? I'm open to suggestions :-) ).

Thoughts?

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 19:12:52.000000000

Patch Set 4:

The CSS solution will work fine, so we should apply this patch that.

The current implementation is that, if theming is turned of, we use the SWT defaults. I don't think we should change that lightly.  Also I'm relatively sure that JDT will reject to use internal API from the CSS engine.  Therefore I suggested to discuss that in a new bug report.

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 19:13:36.000000000

Patch Set 4:

s/The CSS solution will work fine, so we should apply this patch that/The CSS solution will work fine, so we use this approach first.
This will solve the issue for the majority of the users.

-------------------------------------
author: Natalia Golden
date: 2016-10-05 19:22:50.000000000

Patch Set 4:

Hello Lars, 

 > The CSS solution will work fine, so we should apply this patch
 > that.
I'm missing something, you don't explain how the pure CSS approach will address the issues outline above. Can you please elaborate?

 > The current implementation is that, if theming is turned of, we use
 > the SWT defaults. I don't think we should change that lightly. 
We are not changing SWT defaults, we are telling Javadoc hover to use an alternate SWT color here.
Also, falling back to SWT defaults makes the Javadoc black again, thus not solving the problem.

 > Also I'm relatively sure that JDT will reject to use internal API
 > from the CSS engine.  Therefore I suggested to discuss that in a
 > new bug report.
Well, I copied the IColorFactory based on RGBVisibleContrastColorFactory found ~10 lines below my RGBPlatformDependentColorFactory, which is inside org.eclipse.ui/plugin.xml. RGBVisibleContrastColorFactory.java is next to RGBPlatformDependentColorFactory. I.e, they already make use of that functionality, I don't see why they would reject an already existing link. It's just more of the same. 

Can you elaborate?

-------------------------------------
author: Natalia Golden
date: 2016-10-05 19:24:21.000000000

Patch Set 4:

> s/The CSS solution will work fine, so we should apply this patch
 > that/The CSS solution will work fine, so we use this approach
 > first.
 > This will solve the issue for the majority of the users.

I don't like the term "majority of the users" :-). I run on an OS used by >1% of desktop users in the world. I would suggest we do one thing that works for everything rather than most people.

-------------------------------------
author: Brock Pruitt
date: 2016-10-05 19:24:52.000000000

Patch Set 4:

Lars, you are overlooking the fact that the system defaults that SWT exposes are for a different thing. Since there is no GTK color for Javadoc, we have to invent it.

-------------------------------------
author: Natalia Golden
date: 2016-10-05 19:25:52.000000000

Patch Set 4:

*Fix in quotation*

 Hello Lars,
 
 > The CSS solution will work fine, so we should apply this patch
 > that.

 I'm missing something, you don't explain how the pure CSS approach
 will address the issues outline above. Can you please elaborate?
 
 > The current implementation is that, if theming is turned of, we use
 > the SWT defaults. I don't think we should change that lightly.

 We are not changing SWT defaults, we are telling Javadoc hover to
 use an alternate SWT color here.
 Also, falling back to SWT defaults makes the Javadoc black again,
 thus not solving the problem.
 
 > Also I'm relatively sure that JDT will reject to use internal API
 > from the CSS engine.  Therefore I suggested to discuss that in a
 > new bug report.
 
 Well, I copied the IColorFactory based on RGBVisibleContrastColorFactory
 found ~10 lines below my RGBPlatformDependentColorFactory, which is
 inside org.eclipse.ui/plugin.xml. RGBVisibleContrastColorFactory.java
 is next to RGBPlatformDependentColorFactory. I.e, they already make
 use of that functionality, I don't see why they would reject an
 already existing link. It's just more of the same.
 
 Can you elaborate?

-------------------------------------
author: Natalia Golden
date: 2016-10-05 19:29:11.000000000

Patch Set 4:

s/org.eclipse.ui/ org.eclipse.JDT.ui/

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 19:51:39.000000000

Patch Set 4:

> Since there is no GTK color for Javadoc, we have to invent it.

I did not dig into the JDT changes Leo did, but AFAIK we have now a preference for the Javadoc color. Why is this color not set to something reasonable? This would be the color we have to set. If it is not set in JDT, we need to fix it in JDT.

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 19:52:47.000000000

Patch Set 4:

> Can you elaborate?

See the answer I gave Sergey.

-------------------------------------
author: Zaid Mosley
date: 2016-10-05 19:55:01.000000000

Patch Set 4:

See https://imgur.com/a/OiPDU

-------------------------------------
author: Natalia Golden
date: 2016-10-05 20:02:58.000000000

Patch Set 4:

> > Since there is no GTK color for Javadoc, we have to invent it.
 > 
 > I did not dig into the JDT changes Leo did, but AFAIK we have now a
 > preference for the Javadoc color. Why is this color not set to
 > something reasonable? This would be the color we have to set. 

I initially suggested that JDT would use COLOR_LIST_* instead of COLOR_INFO_*, however, that would mean that Javadoc no longer has the 'yellow' background on Windows. See:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=500196#c13
I.e, Sebastian Porter opposes COLOR_LIST_*. I investigated, there is no other suitable color for Javadoc other than COLOR_LIST_*. Thus the IColorFactory solution preserves looks on Windows yet fixes things on Linux.


 > If it is not set in JDT, we need to fix it in JDT.

Well, in order for JDT to fix it on their end, we need this factory in *ui.workLeon Ochoach. Thus the two separate patch submissions.

Thoughts?

-------------------------------------
author: Brock Pruitt
date: 2016-10-05 22:11:48.000000000

Patch Set 4:

> I initially suggested that JDT would use COLOR_LIST_* instead of
> COLOR_INFO_*, however, that would mean that Javadoc no longer has
> the 'yellow' background on Windows. See:
> https://bugs.eclipse.org/bugs/show_bug.cgi?id=500196#c13
> I.e, Sebastian Porter opposes COLOR_LIST_*. I investigated, there is no
> other suitable color for Javadoc other than COLOR_LIST_*. Thus the
> IColorFactory solution preserves looks on Windows yet fixes things
> on Linux.

Another option is to hardcode the yellow color matching the one on Windows in JDT so that it applies to all platforms. This happens to be my favorite color BTW.

-------------------------------------
author: Zaid Mosley
date: 2016-10-06 12:01:47.000000000

Patch Set 4:

> Another option is to hardcode the yellow color matching the one on Windows in JDT so that it applies to all platforms. This happens to be my favorite color BTW.

+1. Or they can put code similar to RGBPlatformDependentColorFactory into their preference initializer.

-------------------------------------
author: Natalia Golden
date: 2016-10-06 14:17:16.000000000

Patch Set 4: -Code-Review

> > Another option is to hardcode the yellow color matching the one
 > on Windows in JDT so that it applies to all platforms. This happens
 > to be my favorite color BTW.
 > 
 > +1. Or they can put code similar to RGBPlatformDependentColorFactory
 > into their preference initializer.

Thank you for feedback. Let me investigate :-).

-------------------------------------
author: Natalia Golden
date: 2016-10-06 16:58:33.000000000

Patch Set 4:

I did some investigation:

 > > Another option is to hardcode the yellow color matching the one
 > on Windows in JDT so that it applies to all platforms. This happens
 > to be my favorite color BTW.

The CSS is a chicken and egg situation. Either you have native on Linux and CSS windows, or you CSS Linux and have native on Windows. This re-introduces the same issue but for Windows users. People who have eclipse themes on windows will have issues (For example Windows high-contrast mode, or it would change look on their black theme). Also, it would also change look in Cocoa not just windows. I may lack context knowledge, it appears to me that a CSS based solution here would not satisfy all parties involved, where as a Factory gives a native feel on each platform.


 > +1. Or they can put code similar to RGBPlatformDependentColorFactory
 > into their preference initializer.

No. We should have it inside org.eclipse.ui.workLeon Ochoach because I was planning on using it to fix HeapStatus.java (among other things..) (which is broken at the moment, it resides in org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/HeapStatus.java.).
Having it inside *.jdt means we can't use it inside platform.
Again, I'm not introducing a new dependency here, I'm just doing the same as RGBVisibleContrastColorFactory. It's also implemented and resides in org.eclipse.ui.internal.themes and it's also used in *jdt (10 lines below where I use it, [see patch 2/2]). 

Unless I'm missing something? The CSS business is not a universal fix, but the ColorFactor is and there is necessity to have it specifically inside org.eclipse.ui.

I mean like, if you guys can change Dani's mind, then I wouldn't mind writing something that involves COLOR_LIST_* based (good luck with that :-)). Otherwise, unless there are further suggestions/concerns, I propose we go ahead with the factory approach. 

What are your thoughts?

-------------------------------------
author: Brock Pruitt
date: 2016-10-06 17:04:47.000000000

Patch Set 4:

The low tech proposal to hardcode the yellow color matching the one on Windows in JDT so that it applies to all platforms hasn't been addressed yet, has it? The default color defined that way would be overridden by css if the theming is enabled.

-------------------------------------
author: Zaid Mosley
date: 2016-10-07 15:07:32.000000000

Patch Set 4: Code-Review-2

Leo contact me via email, why I dislike the approach taken here. Here is a short summary:

- JDT should not rely on internal code from platform UI and the CSS engine is internal API
- Platform UI is not reponsible for defining colors for JDT (layer breakage)
- The color factory approach is not related to CSS styling, hence the CSS plug-in in the wrong place to put the factory in
- All other default JDT colors are (and should be) defined in JDT

I see several solutions:

1.) Use CSS to style the Javadoc view -> This would be inline with the CSS engine but would not help non CSS users
2.) Set the color correctly in JDT
2.a.) hard-coded 
2.b.) dynamically via color factory or preference initialize

-------------------------------------
author: Natalia Golden
date: 2016-10-07 15:26:47.000000000

Patch Set 4: Code-Review-1

I need to do some research and investigation on the matter.

Let's hold off for now.

-------------------------------------
author: Natalia Golden
date: 2016-10-11 14:27:34.000000000

Patch Set 4:

@Lars

Thank you for your feedback. As a note:

 > - JDT should not rely on internal code from platform UI and the CSS
 > engine is internal API

Fair point. But as a note, this currently is already being done by RGBVisibleContrastColorFactory.



 > - Platform UI is not reponsible for defining colors for JDT (layer
 > breakage)

I see your reasoning and perhaps there is ambiguity in the bug title. What I failed to outline is that the issue is not specific to JDT. For example here's a hover with the same color issue in CDT:
https://bugs.eclipse.org/bugs/attachment.cgi?id=264778
My line of thought was to define a factory once and re-use it for plugins that build on platform. Otherwise we'd have to duplicate the factory code across plugins.

Maybe make the RGBPlatformDependentColorFactory public or research if we can change SWT's COLOR_INFO itself... 

 > - The color factory approach is not related to CSS styling, hence
 > the CSS plug-in in the wrong place to put the factory in

Well, unless I'm missing something, the ColorFactory is defined in workLeon Ochoach, it is not in the CSS plugin? Did you miss-read the file name location? I don't fully understand, can you clarify?
Only the first file (e4-dark_preferencestyle.css) is in the css theme plugin. But this is just for javadoc to look proper on dark theme. Is this an issue? I could take it out. This file is also not related to the Javadoc on regular Eclipse, only specifically for Javadoc on black theme.


 > - All other default JDT colors are (and should be) defined in JDT

Well, technically the first part of that statement is not true. As an example, JDT uses RGBVisibleContrastColorFactory which is in ui.workLeon Ochoach. So not all JDT colors are defined in JDT. I can understand your reasoning that JDT should define it's colors. But what about other plugins like CDT? Should they be duplicating ColorFactory into their code also?

 > I see several solutions:
 > 
 > 1.) Use CSS to style the Javadoc view -> This would be inline with
 > the CSS engine but would not help non CSS users

On the grounds that this doesn't work for some users, I think we should work on a more universal solution.

 > 2.) Set the color correctly in JDT

Dani opposes using COLOR_LIST_* for Javadoc. Moving ColorFactory to JDT would mean we'd have to duplicate it in other plugins like CDT. Is this duplication desired?
We could propose to use COLOR_LIST_* with windows CSS styling to Dani and see what he thinks... 

 > 2.a.) hard-coded

Hard coding in CSS doesn't work when the CSS engine is disabled and hard coding in preference leads to inconsistent colors when native theme differs from usual 'white background/black foreground' (ex high contrast).


 > 2.b.) dynamically via color factory or preference initialize

(btw is 2.b a reference to this solution or a different approach?)


In any case, I need to do some more research on the matter. At the moment I'm busy with the webkit2 port, I'll get back to this bug some time later.

-------------------------------------
author: Natalia Golden
date: 2016-10-11 14:29:56.000000000

Patch Set 4:

@ Lars, 

What about defining a general purpose "Hover" fore/background color and preference in platform, and then get JDT to use that?

-------------------------------------
author: Brock Pruitt
date: 2016-10-11 15:26:29.000000000

Patch Set 4:

"Documentation Hover" would be a better term because one can imagine hovers of different colors used for different purposes.

-------------------------------------
author: Zaid Mosley
date: 2016-10-11 18:50:39.000000000

Patch Set 4:

@Leo, the definition of a new general color (not via internal API) would be a great solution. I open a bug for this, and add the interested parties to it.

-------------------------------------
author: Natalia Golden
date: 2016-10-17 15:06:01.000000000

Abandoned

The functionality will be persued further in:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=505738

-------------------------------------
