Description Felix Hirsch 2016-10-17 05:31:27 EDT

Created attachment 264885 [details]
Created disabled images for different controls for all platforms

The rendering of disabled images is partly incorrect and inconsistent within each system. 
Under windows the rendering methods create mostly very poor images. 
In some cases SWT methods doesn't behave like they are documented and at the same time the eclipse user interface guidelines are violated as well.

I attach a PNG file to this report which shows the results of my analysis. I will also attach a zip file containing a java example with which I created the results from within a Eclipse 4.6.1 Neon IDE for each platform.


Let me explain my statement.

I took a closer look how disabled images are rendered with SWT on the following platforms:
* Windows 7 and 10
* Linux RedHat 6.8 and Ubuntu 16.10 (only for GTK2, see bug #495004) 
* MacOS X (Yosemite 10.10.3)

In my analysis I considered the implicite (and if available, also the explicite) rendering methods for the controls 
* ToolItem
* Label
* Button 
* and MenuItem.

Further I also checked how the Image class copy constructor renders with the flags 
* SWT.IMAGE_DISABLE and 
* SWT.IMAGE_GRAY.


Windows
-------
* The rendering under Windows is in most cases (sorry for my hard words) ugly or as stated in the eclipse user interface guidelines very "poor". 

* The MenuItem differs here from all other controls. The images for MenuItems are rendered NICE using a system internal way. 

* All other implicitly rendered disabled images under Windows are rendered using the copy constructor of the Image class with the flag SWT.IMAGE_DISABLE, which is poor, but at least *consistently poor over all PLATFORMS*. 

* Using the constant SWT.IMAGE_GRAY is also consistently the same for all platforms, but the created images look definitely nicer.

* It is currently not possible to enhance the quality of disabled images in Buttons and Label. For the ToolItem there exists a workaround:



Workaround for ToolItems (specified for all PLATFORMS)
------------------------------------------------------
* For ToolItems one can use the interface method ToolItem#setDisabledImage to explicitly provide a disabled image. This way is also suggested in the user interface guidelines for ALL PLATFORMS. 

* Under Windows this works as it is described.



Linux and MacOS
---------------
* Under Linux and MacOS the ToolItem interface methods for providing disabled images, as described above, are ignored (Linux) or the images are taken but changed by the system (MacOS). 

* Therefore the interface contract of the class ToolItem is violated and the "Eclipse User Interface Guidelines" described in https://wiki.eclipse.org/User_Interface_Guidelines#States can never be followed while using the SWT implementation under Linux and MacOS.

Let me explain and support that last statement. 

In the Javadoc for the method ToolItem#setDisabledImage states:
	
	"Sets the receiver's disabled image to the argument, which may be null indicating that no disabled image should be displayed. The disabled image is displayed when the receiver is disabled."

And in the eclipse user interface guidelines it is written:
	
	"It is important to implement the graphical versions of the disabled state for toolbar and local toolbar icons. The quality and legibility of algorithmically rendered disabled icons is poor and they are not consistent with the majority of other tools that use the graphical versions."

In both documentations there is no note made about platform dependent behavior and further the interfaces documentation says that the provided images WILL BE USED for the control when disabled.



Let me summarize and complete the issue topics from this report
---------------------------------------------------------------
* Windows renders disabled images very POOR except for MenuItems.

* There is no way to render disabled images in all cases with the method/algorithm (Windows) or the user/developer does not have any access to the internal method (Linux, MacOS).

* The suggested workaround to use explicitly provided disabled images is only available for ToolItem controls but is MISSING for Label, Button and MenuItem controls.

* Linux IGNORES explicitly provided disabled images for ToolItems (Violation of style guide and interface contract)

* MacOS uses explicitly provided disabled images for ToolItems but CHANGES them (Violation of style guide and interface contract)

* Under MacOS the label image is not displayed in a disabled way. This might be OK, since a label is a none-interactive control and in the Javadoc it is stated, that the control is displayed only "typically" in "grayed" look.


Suggestions
-----------
* With currently available Windows versions it should be possible to use better internal rendering methods. This is actually already done for the MenuItem. All controls under Windows should render implicitly disabled images NICELY using ONE CENTRALIZED METHOD.

* The user of the framework should be able to create NICE images in the SAME disabled look. Therefore the Image copy constructor should use the SAME NICE method. This is IMPORTANT, as one can create her/his own controls which  should have the same look and feel possibilities for a disabled state. 

* It would also be a great achievement, if one could provide alternative strategies at runtime to explicitly specify the algorithm which is used for rendering disabled images.

* I would prefer to DEPRECATE (REMOVE) the "workaround" interface for ToolItems OR at least to provide all image containing controls with this interface. But better have it marked deprecated. 
If the first suggestion ("Nicer disabled images and a central way to access or even specify the rendering method") is fulfilled, there is no need to keep the workaround interface any longer in my opinion.

* As long as the workaround will stay active and is not marked as deprecated in the interface, Linux and MacOS should behave like the contract states.