com.smartgwt.client.docs

Interface BrowserZoom

public interface BrowserZoom

Native Browser Zoom Support

Native browser zooming, that is, the ability in most browsers to enlarge or shrink the entire web page, is currently only partly supported in specific browsers due to intractable browser bugs.

Support in this release is restricted to:

• support for almost all components for Internet Explorer version 11 only, with known issues, almost all cosmetic (see below)
• supported with the requirement that users refresh the page after changing zoom, with known cosmetic issues listed below. See also the Detecting Zoom Changes section below.
• no support for Chrome, Safari, other Webkit browsers - support not yet possible (see below)

In addition, support guarantees are limited for zoom-related issues:

• cosmetic issues that appear only in zoom mode will not be investigated
• functional issues that appear only in zoom mode will be investigated if they are reproducible, but the normal guarantee of a fix or workaround is not provided, since for most zoom issues, there is no feasible way to work around the problem

Known issues by browser are listed below.

Chrome and Opera 15+

• Core DOM APIs for querying position and sizing information of an element return fractional values even though they shouldn't be, which can impact layout, scrolling, and event handling. See issue 60837.
• The minimum font size feature can cause layout issues when the page zoom is decreased but the page is not refreshed at the new zoom level.
• Chrome fails background-image related CSS Working Group tests with page zoom, causing background images to draw oddly in certain cases. See issues 412914 and 421331.
• Borders do not scale properly, causing layout issues, cosmetic issues where borders do not line up with background images or appear beveled, and accessibility issues where borders may be too thin. See issues 257220, 382483, 388879, 406371, and 434720.
• Various issues affecting SVG drawings. See issues 181122, 407159, and 421926.

Firefox

• Firefox' approach to page zoom involves changing the layout rather than scaling the entire page content by the zoom factor. This can cause layout and scrolling issues if the zoom level is changed without refreshing the page. See A Tale Of Two Zooms.
• Like Chrome and Safari, Firefox has a minimum font size feature which may cause layout issues when the page zoom is changed without refreshing the page at the new zoom level. See bug 912159.
• On Windows and Linux, native checkbox and radio button inputs do not scale with the page zoom. See bug 400364.
• A focus outline might not be drawn around the focus element when zoomed. See bug 1050753.
• The form element autocomplete box does not move when the page zoom is changed. See bug 731150.

Internet Explorer

• IE may draw "seams" on EdgedCanvas objects, which are faint antialiasing artifacts between the images used to make up the EdgedCanvas. This affects drop shadows and showing edges with a high Canvas.edgeSize. See issue 808337.
• Phantom borders may appear between table cells and other content that should be adjacent with no separation. This issue is also thought to be the cause of a line appearing below a selected TabSet tab at certain zoom levels. See issues 808838 and 814033.
• SVG content may disappear at high zoom levels. See issue 782997.

Safari and WebKit

• Core DOM APIs for querying sizing information of an element may overstate a dimension, which can impact layout, scrolling, and event handling.
• Like Chrome and Firefox, Safari supports a minimum font size feature. This can cause layout issues to appear when the page zoom is decreased but the page is not refreshed at the new zoom level.
• CSS background-position and background image clipping used for spriting may be misapplied. This can introduce visual effects where different parts of a sprite are visible. See bug 45840.
• Background images can be misdrawn at certain zoom levels, where the first or last row or column of pixels in the image "wrap" to the other side. See bug 125133.
• Transparent 1px-wide gaps can appear around the content area of an EdgedCanvas, allowing content below the EdgedCanvas in stacking order to show through. See bug 122061.
• A phantom line may appear below a selected TabSet tab at certain zoom levels.

Detecting Zoom Changes

There is no officially supported cross-browser way of detecting zoom, and current approaches rely on hacks that browser vendors seem willing to break or deprecate. These current approaches are described at How to detect page zoom level in all modern browsers? with a small proof-of-concept JavaScript library called detect-zoom.

Although the detect-zoom library does not accurately determine the current zoom level, the library can be used in Firefox to detect when the zoom level changes so that a warning message can be displayed to the user.

Note that the latest version of detect-zoom.min.js that is committed to the GitHub repository is out of date. It is not recommended to use this file because it causes a runtime TypeError if the script is included before the document body has been created (see issue #41). To rebuild detect-zoom.min.js, you will need to install git, npm, and GNU make. Then at a terminal, run the following commands:

git clone https://github.com/tombigel/detect-zoom.git
 cd detect-zoom
 npm install
 touch detect-zoom.js && make

To use the detect-zoom library in your Smart GWT project:

• Rebuild the detect-zoom.min.js script.
• Create a directory called public in the same directory as your GWT module. For example, if your GWT module is located at com/mycompany/Product.gwt.xml then create the com/mycompany/public directory if it does not already exist. Copy the rebuilt detect-zoom.min.js script to this public directory.
• Add the following <script> tag to your GWT module definition:

  <script src="detect-zoom.min.js"/>

• Add the following JSNI method that calls the detectZoom.zoom() API:

      public static native double detectZoom() /*-{
           return $wnd.detectZoom.zoom();
       }-*/;

• When your module's EntryPoint is called, call the detectZoom() static method and save the return value. Then add a window resize handler (see Window.addResizeHandler(com.google.gwt.event.logical.shared.ResizeHandler)) that calls detectZoom() on resize, checking to see if a different value is returned.

Here is a complete example:

import com.google.gwt.core.client.EntryPoint;
 import com.google.gwt.event.logical.shared.ResizeEvent;
 import com.google.gwt.event.logical.shared.ResizeHandler;
 import com.google.gwt.user.client.Window;
 import com.smartgwt.client.util.SC;
 
 public class MyEntryPoint implements EntryPoint {
 
     public static native double detectZoom() /*-{
         return $wnd.detectZoom.zoom();
     }-*/;
 
     @Override
     public void onModuleLoad() {
         //...
 
         Window.addResizeHandler(new ResizeHandler() {
             private double lastZoom = detectZoom();
 
             @Override
             public void onResize(ResizeEvent event) {
                 final double newZoom = detectZoom();
                 if (newZoom != lastZoom) {
                     lastZoom = newZoom;
                     SC.warn("After changing the page zoom, you must refresh the page.");
                 }
             }
         });
     }
 }