Implement a monitor-aware lightweight system to handle HiDPI scaling

This lightweight-system disables the native HiDPI scaling that is
normally done by SWT and instead scales the figures via a
ScalableLayeredPane.

The main purpose of this class is to reduce the noise that is introduced
by rounding, errors when dealing with fractional scaling.

To test this functionality, simply pass the MonitorAwareLightweighSystem
as an additional argument when constructing the FigureCanvas. See the
AutoScaleExample for reference

Author: ptziegler

.gitignore

@@ -1,6 +1,7 @@
 **/bin/
 **/target/
 **/guide/**/*.html
+**/guide/**/*.svg
 /gef-updates
 *~
 *.rej

org.eclipse.draw2d.doc.isv/guide-src/guide.adoc

@@ -20,3 +20,4 @@ coordinates, working with absolute coordinates
 behavior
 * xref:migration-guide.adoc[Plug-in Migration Guide] - changes between
 individual releases
+* xref:hidpi.adoc[High-DPI Support] - taming the native display zoom

org.eclipse.draw2d.doc.isv/guide-src/hidpi.adoc

@@ -0,0 +1,44 @@
+ifdef::env-github[]
+:imagesdir: ../guide/
+endif::[]
+
+= High-DPI Support
+
+Modern versions of SWT automatically scale the Draw2D figures by the native display zoom. In Draw2D, this feature is
+enabled by default. If clients require more control over the scaling behavior, this functionality may be configured by
+passing a link:../reference/api/org/eclipse/draw2d/MonitorAwareLightweightSystem.html[`MonitorAwareLightweightSystem`],
+when creating a new link:../reference/api/org/eclipse/draw2d/FigureCanvas.html[`FigureCanvas`] instance.
+
+[source,java]
+----
+FigureCanvas figureCanvas = new FigureCanvas(shell, new MonitorAwareLightweightSystem());
+----
+
+This custom lightweight-system performs three actions:
+
+1) It disables the auto-scaling that would normally be done by SWT, by setting the widget-defined `AUTOSCALE_DISABLED`
+   property.
+
+2) It creates a link:../reference/api/org/eclipse/draw2d/internal/MonitorAwareViewport.html[`MonitorAwareViewport`] that is used
+   to inject a link:../reference/api/org/eclipse/draw2d/ScalableLayeredPane.html[`ScalableLayeredPane`] between the root figure
+   and the contents of the viewport.
+
+3) It hooks a listener to the canvas that updates the scale of the scalable pane, whenever the native zoom of the widget
+   is changed.
+
+image:images/hidpi-lws.png[Figure Hierarchy of the MonitorAwareLightweightSystem]
+
+Clients may optionally set the `draw2d.autoScale` system property to define a scaling that is independent from the display zoom.
+Similar to the SWT system property, the value must be a positive integer.
+
+Example: 100, 125, 200, which correlate to 100%, 125% and 200%.
+
+In order to use this custom LightweightSystem in a GEF view, override the `createLightweightSystem()` method of the
+`GraphicalViewerImpl`.
+
+[source,java]
+----
+protected LightweightSystem createLightweightSystem() {
+	return new MonitorAwareLightweightSystem();
+}
+----

org.eclipse.draw2d.doc.isv/guide-src/images/hidpi-lws.svg

@@ -15,6 +15,8 @@
 		<topic label="User-specific Extensions" href="guide/extensions.html" />
   <topic href="guide/migration-guide.html" label="Plug-in Migration Guide">
   </topic>
+  <topic href="guide/hidpi.html" label="High-DPI Support">
+  </topic>
   <topic href="guide/demos/index.html" label="Examples">
      <topic href="guide/demos/demo1.html" label="Hello World">
      </topic>