1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
|
/*
* Copyright (C) 2006 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.view;
import android.graphics.PixelFormat;
import android.graphics.Point;
import android.graphics.Rect;
import android.hardware.display.DisplayManagerGlobal;
import android.os.SystemClock;
import android.util.DisplayMetrics;
import android.util.Log;
/**
* Provides information about the size and density of a logical display.
* <p>
* The display area is described in two different ways.
* <ul>
* <li>The application display area specifies the part of the display that may contain
* an application window, excluding the system decorations. The application display area may
* be smaller than the real display area because the system subtracts the space needed
* for decor elements such as the status bar. Use the following methods to query the
* application display area: {@link #getSize}, {@link #getRectSize} and {@link #getMetrics}.</li>
* <li>The real display area specifies the part of the display that contains content
* including the system decorations. Even so, the real display area may be smaller than the
* physical size of the display if the window manager is emulating a smaller display
* using (adb shell am display-size). Use the following methods to query the
* real display area: {@link #getRealSize}, {@link #getRealMetrics}.</li>
* </ul>
* </p><p>
* A logical display does not necessarily represent a particular physical display device
* such as the built-in screen or an external monitor. The contents of a logical
* display may be presented on one or more physical displays according to the devices
* that are currently attached and whether mirroring has been enabled.
* </p>
*/
public final class Display {
private static final String TAG = "Display";
private static final boolean DEBUG = false;
private final DisplayManagerGlobal mGlobal;
private final int mDisplayId;
private final int mLayerStack;
private final String mName;
private final CompatibilityInfoHolder mCompatibilityInfo;
private DisplayInfo mDisplayInfo; // never null
private boolean mIsValid;
// Temporary display metrics structure used for compatibility mode.
private final DisplayMetrics mTempMetrics = new DisplayMetrics();
// We cache the app width and height properties briefly between calls
// to getHeight() and getWidth() to ensure that applications perceive
// consistent results when the size changes (most of the time).
// Applications should now be using getSize() instead.
private static final int CACHED_APP_SIZE_DURATION_MILLIS = 20;
private long mLastCachedAppSizeUpdate;
private int mCachedAppWidthCompat;
private int mCachedAppHeightCompat;
/**
* The default Display id, which is the id of the built-in primary display
* assuming there is one.
*/
public static final int DEFAULT_DISPLAY = 0;
/**
* Internal method to create a display.
* Applications should use {@link android.view.WindowManager#getDefaultDisplay()}
* or {@link android.hardware.display.DisplayManager#getDisplay}
* to get a display object.
*
* @hide
*/
public Display(DisplayManagerGlobal global,
int displayId, DisplayInfo displayInfo /*not null*/,
CompatibilityInfoHolder compatibilityInfo) {
mGlobal = global;
mDisplayId = displayId;
mDisplayInfo = displayInfo;
mLayerStack = displayInfo.layerStack; // can never change as long as the display is valid
mName = displayInfo.name; // cannot change as long as the display is valid
mCompatibilityInfo = compatibilityInfo;
mIsValid = true;
}
/**
* Gets the display id.
* <p>
* Each logical display has a unique id.
* The default display has id {@link #DEFAULT_DISPLAY}.
* </p>
*/
public int getDisplayId() {
return mDisplayId;
}
/**
* Returns true if this display is still valid, false if the display has been removed.
*
* If the display is invalid, then the methods of this class will
* continue to report the most recently observed display information.
* However, it is unwise (and rather fruitless) to continue using a
* {@link Display} object after the display's demise.
*
* It's possible for a display that was previously invalid to become
* valid again if a display with the same id is reconnected.
*
* @return True if the display is still valid.
*/
public boolean isValid() {
synchronized (this) {
updateDisplayInfoLocked();
return mIsValid;
}
}
/**
* Gets a full copy of the display information.
*
* @param outDisplayInfo The object to receive the copy of the display information.
* @return True if the display is still valid.
* @hide
*/
public boolean getDisplayInfo(DisplayInfo outDisplayInfo) {
synchronized (this) {
updateDisplayInfoLocked();
outDisplayInfo.copyFrom(mDisplayInfo);
return mIsValid;
}
}
/**
* Gets the display's layer stack.
*
* Each display has its own independent layer stack upon which surfaces
* are placed to be managed by surface flinger.
*
* @return The display's layer stack number.
* @hide
*/
public int getLayerStack() {
return mLayerStack;
}
/**
* Gets the compatibility info used by this display instance.
*
* @return The compatibility info holder, or null if none is required.
* @hide
*/
public CompatibilityInfoHolder getCompatibilityInfo() {
return mCompatibilityInfo;
}
/**
* Gets the name of the display.
* @return The display's name.
*/
public String getName() {
return mName;
}
/**
* Gets the size of the display, in pixels.
* <p>
* Note that this value should <em>not</em> be used for computing layouts,
* since a device will typically have screen decoration (such as a status bar)
* along the edges of the display that reduce the amount of application
* space available from the size returned here. Layouts should instead use
* the window size.
* </p><p>
* The size is adjusted based on the current rotation of the display.
* </p><p>
* The size returned by this method does not necessarily represent the
* actual raw size (native resolution) of the display. The returned size may
* be adjusted to exclude certain system decoration elements that are always visible.
* It may also be scaled to provide compatibility with older applications that
* were originally designed for smaller displays.
* </p>
*
* @param outSize A {@link Point} object to receive the size information.
*/
public void getSize(Point outSize) {
synchronized (this) {
updateDisplayInfoLocked();
mDisplayInfo.getAppMetrics(mTempMetrics, mCompatibilityInfo);
outSize.x = mTempMetrics.widthPixels;
outSize.y = mTempMetrics.heightPixels;
}
}
/**
* Gets the size of the display as a rectangle, in pixels.
*
* @param outSize A {@link Rect} object to receive the size information.
* @see #getSize(Point)
*/
public void getRectSize(Rect outSize) {
synchronized (this) {
updateDisplayInfoLocked();
mDisplayInfo.getAppMetrics(mTempMetrics, mCompatibilityInfo);
outSize.set(0, 0, mTempMetrics.widthPixels, mTempMetrics.heightPixels);
}
}
/**
* Return the range of display sizes an application can expect to encounter
* under normal operation, as long as there is no physical change in screen
* size. This is basically the sizes you will see as the orientation
* changes, taking into account whatever screen decoration there is in
* each rotation. For example, the status bar is always at the top of the
* screen, so it will reduce the height both in landscape and portrait, and
* the smallest height returned here will be the smaller of the two.
*
* This is intended for applications to get an idea of the range of sizes
* they will encounter while going through device rotations, to provide a
* stable UI through rotation. The sizes here take into account all standard
* system decorations that reduce the size actually available to the
* application: the status bar, navigation bar, system bar, etc. It does
* <em>not</em> take into account more transient elements like an IME
* soft keyboard.
*
* @param outSmallestSize Filled in with the smallest width and height
* that the application will encounter, in pixels (not dp units). The x
* (width) dimension here directly corresponds to
* {@link android.content.res.Configuration#smallestScreenWidthDp
* Configuration.smallestScreenWidthDp}, except the value here is in raw
* screen pixels rather than dp units. Your application may of course
* still get smaller space yet if, for example, a soft keyboard is
* being displayed.
* @param outLargestSize Filled in with the largest width and height
* that the application will encounter, in pixels (not dp units). Your
* application may of course still get larger space than this if,
* for example, screen decorations like the status bar are being hidden.
*/
public void getCurrentSizeRange(Point outSmallestSize, Point outLargestSize) {
synchronized (this) {
updateDisplayInfoLocked();
outSmallestSize.x = mDisplayInfo.smallestNominalAppWidth;
outSmallestSize.y = mDisplayInfo.smallestNominalAppHeight;
outLargestSize.x = mDisplayInfo.largestNominalAppWidth;
outLargestSize.y = mDisplayInfo.largestNominalAppHeight;
}
}
/**
* Return the maximum screen size dimension that will happen. This is
* mostly for wallpapers.
* @hide
*/
public int getMaximumSizeDimension() {
synchronized (this) {
updateDisplayInfoLocked();
return Math.max(mDisplayInfo.logicalWidth, mDisplayInfo.logicalHeight);
}
}
/**
* @deprecated Use {@link #getSize(Point)} instead.
*/
@Deprecated
public int getWidth() {
synchronized (this) {
updateCachedAppSizeIfNeededLocked();
return mCachedAppWidthCompat;
}
}
/**
* @deprecated Use {@link #getSize(Point)} instead.
*/
@Deprecated
public int getHeight() {
synchronized (this) {
updateCachedAppSizeIfNeededLocked();
return mCachedAppHeightCompat;
}
}
/**
* Returns the rotation of the screen from its "natural" orientation.
* The returned value may be {@link Surface#ROTATION_0 Surface.ROTATION_0}
* (no rotation), {@link Surface#ROTATION_90 Surface.ROTATION_90},
* {@link Surface#ROTATION_180 Surface.ROTATION_180}, or
* {@link Surface#ROTATION_270 Surface.ROTATION_270}. For
* example, if a device has a naturally tall screen, and the user has
* turned it on its side to go into a landscape orientation, the value
* returned here may be either {@link Surface#ROTATION_90 Surface.ROTATION_90}
* or {@link Surface#ROTATION_270 Surface.ROTATION_270} depending on
* the direction it was turned. The angle is the rotation of the drawn
* graphics on the screen, which is the opposite direction of the physical
* rotation of the device. For example, if the device is rotated 90
* degrees counter-clockwise, to compensate rendering will be rotated by
* 90 degrees clockwise and thus the returned value here will be
* {@link Surface#ROTATION_90 Surface.ROTATION_90}.
*/
public int getRotation() {
synchronized (this) {
updateDisplayInfoLocked();
return mDisplayInfo.rotation;
}
}
/**
* @deprecated use {@link #getRotation}
* @return orientation of this display.
*/
@Deprecated
public int getOrientation() {
return getRotation();
}
/**
* Gets the pixel format of the display.
* @return One of the constants defined in {@link android.graphics.PixelFormat}.
*
* @deprecated This method is no longer supported.
* The result is always {@link PixelFormat#RGBA_8888}.
*/
@Deprecated
public int getPixelFormat() {
return PixelFormat.RGBA_8888;
}
/**
* Gets the refresh rate of this display in frames per second.
*/
public float getRefreshRate() {
synchronized (this) {
updateDisplayInfoLocked();
return mDisplayInfo.refreshRate;
}
}
/**
* Gets display metrics that describe the size and density of this display.
* <p>
* The size is adjusted based on the current rotation of the display.
* </p><p>
* The size returned by this method does not necessarily represent the
* actual raw size (native resolution) of the display. The returned size may
* be adjusted to exclude certain system decor elements that are always visible.
* It may also be scaled to provide compatibility with older applications that
* were originally designed for smaller displays.
* </p>
*
* @param outMetrics A {@link DisplayMetrics} object to receive the metrics.
*/
public void getMetrics(DisplayMetrics outMetrics) {
synchronized (this) {
updateDisplayInfoLocked();
mDisplayInfo.getAppMetrics(outMetrics, mCompatibilityInfo);
}
}
/**
* Gets the real size of the display without subtracting any window decor or
* applying any compatibility scale factors.
* <p>
* The size is adjusted based on the current rotation of the display.
* </p><p>
* The real size may be smaller than the physical size of the screen when the
* window manager is emulating a smaller display (using adb shell am display-size).
* </p>
*
* @param outSize Set to the real size of the display.
*/
public void getRealSize(Point outSize) {
synchronized (this) {
updateDisplayInfoLocked();
outSize.x = mDisplayInfo.logicalWidth;
outSize.y = mDisplayInfo.logicalHeight;
}
}
/**
* Gets display metrics based on the real size of this display.
* <p>
* The size is adjusted based on the current rotation of the display.
* </p><p>
* The real size may be smaller than the physical size of the screen when the
* window manager is emulating a smaller display (using adb shell am display-size).
* </p>
*
* @param outMetrics A {@link DisplayMetrics} object to receive the metrics.
*/
public void getRealMetrics(DisplayMetrics outMetrics) {
synchronized (this) {
updateDisplayInfoLocked();
mDisplayInfo.getLogicalMetrics(outMetrics, null);
}
}
private void updateDisplayInfoLocked() {
// Note: The display manager caches display info objects on our behalf.
DisplayInfo newInfo = mGlobal.getDisplayInfo(mDisplayId);
if (newInfo == null) {
// Preserve the old mDisplayInfo after the display is removed.
if (mIsValid) {
mIsValid = false;
if (DEBUG) {
Log.d(TAG, "Logical display " + mDisplayId + " was removed.");
}
}
} else {
// Use the new display info. (It might be the same object if nothing changed.)
mDisplayInfo = newInfo;
if (!mIsValid) {
mIsValid = true;
if (DEBUG) {
Log.d(TAG, "Logical display " + mDisplayId + " was recreated.");
}
}
}
}
private void updateCachedAppSizeIfNeededLocked() {
long now = SystemClock.uptimeMillis();
if (now > mLastCachedAppSizeUpdate + CACHED_APP_SIZE_DURATION_MILLIS) {
updateDisplayInfoLocked();
mDisplayInfo.getAppMetrics(mTempMetrics, mCompatibilityInfo);
mCachedAppWidthCompat = mTempMetrics.widthPixels;
mCachedAppHeightCompat = mTempMetrics.heightPixels;
mLastCachedAppSizeUpdate = now;
}
}
// For debugging purposes
@Override
public String toString() {
synchronized (this) {
updateDisplayInfoLocked();
mDisplayInfo.getAppMetrics(mTempMetrics, mCompatibilityInfo);
return "Display id " + mDisplayId + ": " + mDisplayInfo
+ ", " + mTempMetrics + ", isValid=" + mIsValid;
}
}
}
|