1
// Copyright 2013 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Utility class that monitors pixel density ratio changes.
17
 *
18
 * @see ../demos/pixeldensitymonitor.html
19
 */
20

21
goog.provide('goog.labs.style.PixelDensityMonitor');
22
goog.provide('goog.labs.style.PixelDensityMonitor.Density');
23
goog.provide('goog.labs.style.PixelDensityMonitor.EventType');
24

25
goog.require('goog.events');
26
goog.require('goog.events.EventTarget');
27

28

29

30
/**
31
 * Monitors the window for changes to the ratio between device and screen
32
 * pixels, e.g. when the user moves the window from a high density screen to a
33
 * screen with normal density. Dispatches
34
 * goog.labs.style.PixelDensityMonitor.EventType.CHANGE events when the density
35
 * changes between the two predefined values NORMAL and HIGH.
36
 *
37
 * This class uses the window.devicePixelRatio value which is supported in
38
 * WebKit and FF18. If the value does not exist, it will always return a
39
 * NORMAL density. It requires support for MediaQueryList to detect changes to
40
 * the devicePixelRatio.
41
 *
42
 * @param {!goog.dom.DomHelper=} opt_domHelper The DomHelper which contains the
43
 *     document associated with the window to listen to. Defaults to the one in
44
 *     which this code is executing.
45
 * @constructor
46
 * @extends {goog.events.EventTarget}
47
 * @final
48
 */
49
goog.labs.style.PixelDensityMonitor = function(opt_domHelper) {
50
  goog.labs.style.PixelDensityMonitor.base(this, 'constructor');
51

52
  /**
53
   * @type {Window}
54
   * @private
55
   */
56
  this.window_ = opt_domHelper ? opt_domHelper.getWindow() : window;
57

58
  /**
59
   * The last density that was reported so that changes can be detected.
60
   * @type {goog.labs.style.PixelDensityMonitor.Density}
61
   * @private
62
   */
63
  this.lastDensity_ = this.getDensity();
64

65
  /**
66
   * @type {function (MediaQueryList)}
67
   * @private
68
   */
69
  this.listener_ = goog.bind(this.handleMediaQueryChange_, this);
70

71
  /**
72
   * The media query list for a query that detects high density, if supported
73
   * by the browser. Because matchMedia returns a new object for every call, it
74
   * needs to be saved here so the listener can be removed when disposing.
75
   * @type {?MediaQueryList}
76
   * @private
77
   */
78
  this.mediaQueryList_ = this.window_.matchMedia ?
79
      this.window_.matchMedia(
80
          goog.labs.style.PixelDensityMonitor.HIGH_DENSITY_QUERY_) :
81
      null;
82
};
83
goog.inherits(goog.labs.style.PixelDensityMonitor, goog.events.EventTarget);
84

85

86
/**
87
 * The two different pixel density modes on which the various ratios between
88
 * physical and device pixels are mapped.
89
 * @enum {number}
90
 */
91
goog.labs.style.PixelDensityMonitor.Density = {
92
  /**
93
   * Mode for older portable devices and desktop screens, defined as having a
94
   * device pixel ratio of less than 1.5.
95
   */
96
  NORMAL: 1,
97

98
  /**
99
   * Mode for newer portable devices with a high resolution screen, defined as
100
   * having a device pixel ratio of more than 1.5.
101
   */
102
  HIGH: 2
103
};
104

105

106
/**
107
 * The events fired by the PixelDensityMonitor.
108
 * @enum {string}
109
 */
110
goog.labs.style.PixelDensityMonitor.EventType = {
111
  /**
112
   * Dispatched when density changes between NORMAL and HIGH.
113
   */
114
  CHANGE: goog.events.getUniqueId('change')
115
};
116

117

118
/**
119
 * Minimum ratio between device and screen pixel needed for high density mode.
120
 * @type {number}
121
 * @private
122
 */
123
goog.labs.style.PixelDensityMonitor.HIGH_DENSITY_RATIO_ = 1.5;
124

125

126
/**
127
 * Media query that matches for high density.
128
 * @type {string}
129
 * @private
130
 */
131
goog.labs.style.PixelDensityMonitor.HIGH_DENSITY_QUERY_ =
132
    '(min-resolution: 1.5dppx), (-webkit-min-device-pixel-ratio: 1.5)';
133

134

135
/**
136
 * Starts monitoring for changes in pixel density.
137
 */
138
goog.labs.style.PixelDensityMonitor.prototype.start = function() {
139
  if (this.mediaQueryList_) {
140
    this.mediaQueryList_.addListener(this.listener_);
141
  }
142
};
143

144

145
/**
146
 * @return {goog.labs.style.PixelDensityMonitor.Density} The density for the
147
 *     window.
148
 */
149
goog.labs.style.PixelDensityMonitor.prototype.getDensity = function() {
150
  if (this.window_.devicePixelRatio >=
151
      goog.labs.style.PixelDensityMonitor.HIGH_DENSITY_RATIO_) {
152
    return goog.labs.style.PixelDensityMonitor.Density.HIGH;
153
  } else {
154
    return goog.labs.style.PixelDensityMonitor.Density.NORMAL;
155
  }
156
};
157

158

159
/**
160
 * Handles a change to the media query and checks whether the density has
161
 * changed since the last call.
162
 * @param {MediaQueryList} mql The list of changed media queries.
163
 * @private
164
 */
165
goog.labs.style.PixelDensityMonitor.prototype.handleMediaQueryChange_ =
166
    function(mql) {
167
  var newDensity = this.getDensity();
168
  if (this.lastDensity_ != newDensity) {
169
    this.lastDensity_ = newDensity;
170
    this.dispatchEvent(goog.labs.style.PixelDensityMonitor.EventType.CHANGE);
171
  }
172
};
173

174

175
/** @override */
176
goog.labs.style.PixelDensityMonitor.prototype.disposeInternal = function() {
177
  if (this.mediaQueryList_) {
178
    this.mediaQueryList_.removeListener(this.listener_);
179
  }
180
  goog.labs.style.PixelDensityMonitor.base(this, 'disposeInternal');
181
};
182

183