Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Revised the API documentation of the getMetrics and getSize methods to account for differences in API levels." am: 7ac639b11b am: d3fd072f68

Browse Source 
Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1957098

Change-Id: I534e88ec19327a174068807996f133740966741e
This commit is contained in:
Jon Eckenrode
2022-03-23 14:55:41 +00:00
committed by Automerger Merge Worker
parent 72f706f60a d3fd072f68
commit bfad78abc6
1 changed files with 68 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
core/java/android/view/Display.java
View File

@@ -741,35 +741,42 @@ public final class Display {
}
/**
* Gets the size of the display, in pixels.
* Value returned by this method does not necessarily represent the actual raw size
* (native resolution) of the display.
* <p>
* 1. The returned size may be adjusted to exclude certain system decor elements
* that are always visible.
* </p><p>
* 2. It may be scaled to provide compatibility with older applications that
* were originally designed for smaller displays.
* </p><p>
* 3. It can be different depending on the WindowManager to which the display belongs.
* </p><p>
* - If requested from non-Activity context (e.g. Application context via
* {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)})
* it will report the size of the entire display based on current rotation and with subtracted
* system decoration areas.
* </p><p>
* - If requested from activity (either using {@code getWindowManager()} or
* {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting size will
* correspond to current app window size. In this case it can be smaller than physical size in
* multi-window mode.
* </p><p>
* Typically for the purposes of layout apps should make a request from activity context
* to obtain size available for the app content.
* </p>
* Gets the size of the display in pixels.
*
* @param outSize A {@link Point} object to receive the size information.
* @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to obtain an instance of
* {@link WindowMetrics} and use {@link WindowMetrics#getBounds()} instead.
* <p>The return value does not necessarily represent the actual size (native resolution) of the
* display. The returned size might be adjusted to exclude certain system decor elements that
* are always visible, or the size might be scaled to provide compatibility with older
* applications that were originally designed for smaller displays.
*
* <p>The returned size can also be different depending on the WindowManager bound to the
* display:
* <ul>
* <li>If size is requested from an activity (either using a WindowManager accessed by
* {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the
* size of the current app window is returned. As a result, in multi-window mode, the
* returned size can be smaller than the size of the device screen.
* <li>If size is requested from a non-activity context (for example, the application
* context, where the WindowManager is accessed by
* {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the
* returned size can vary depending on API level:
* <ul>
* <li>API level 29 and below &mdash; The size of the entire display (based on
* current rotation) minus system decoration areas is returned.
* <li>API level 30 and above &mdash; The size of the top running activity in the
* current process is returned. If the current process has no running
* activities, the size of the device default display, including system
* decoration areas, is returned.
* </ul>
* </ul>
*
* <p>For layout purposes, apps should make a request from an activity context to obtain the
* size of the display area available for app content.
*
* @param outSize A {@link Point} object which receives the display size information.
*
* @deprecated Use {@link WindowMetrics} instead. Obtain a {@code WindowMetrics} instance by
* calling {@link WindowManager#getCurrentWindowMetrics()}, then call
* {@link WindowMetrics#getBounds()} to get the dimensions of the application window.
*/
@Deprecated
public void getSize(Point outSize) {
@@ -785,8 +792,9 @@ public final class Display {
* Gets the size of the display as a rectangle, in pixels.
*
* @param outSize A {@link Rect} object to receive the size information.
*
* @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application
* window area.
* window.
*/
@Deprecated
public void getRectSize(Rect outSize) {
@@ -1275,32 +1283,39 @@ public final class Display {
}
/**
* Gets display metrics that describe the size and density of this display.
* The size returned by this method does not necessarily represent the
* actual raw size (native resolution) of the display.
* <p>
* 1. The returned size may be adjusted to exclude certain system decor elements
* that are always visible.
* </p><p>
* 2. It may be scaled to provide compatibility with older applications that
* were originally designed for smaller displays.
* </p><p>
* 3. It can be different depending on the WindowManager to which the display belongs.
* </p><p>
* - If requested from non-Activity context (e.g. Application context via
* {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)})
* metrics will report the size of the entire display based on current rotation and with
* subtracted system decoration areas.
* </p><p>
* - If requested from activity (either using {@code getWindowManager()} or
* {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting metrics will
* correspond to current app window metrics. In this case the size can be smaller than physical
* size in multi-window mode.
* </p>
* Gets the size and density of this display.
*
* <p>The size returned does not necessarily represent the actual size (native resolution) of
* the display. The returned size might be adjusted to exclude certain system decor elements
* that are always visible, or the size might be scaled to provide compatibility with older
* applications that were originally designed for smaller displays.
*
* <p>The returned size can also be different depending on the WindowManager associated with the
* display:
* <ul>
* <li>If metrics are requested from an activity (either using a WindowManager accessed by
* {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the
* returned metrics provide the size of the current app window. As a result, in
* multi-window mode, the returned size can be smaller than the size of the device
* screen.
* <li>If metrics are requested from a non-activity context (for example, the application
* context, where the WindowManager is accessed by
* {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the
* returned size can vary depending on API level:
* <ul>
* <li>API level 29 and below &mdash; The returned metrics provide the size of the
* entire display (based on current rotation) minus system decoration areas.
* <li>API level 30 and above &mdash; The returned metrics provide the size of the
* top running activity in the current process. If the current process has no
* running activities, the metrics provide the size of the default display of
* the device, including system decoration areas.
* </ul>
* </ul>
*
* @param outMetrics A {@link DisplayMetrics} object which receives the display metrics.
*
* @param outMetrics A {@link DisplayMetrics} object to receive the metrics.
* @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application
* window area, and {@link Configuration#densityDpi} to get the current density.
* window. Use {@link Configuration#densityDpi} to get the display density.
*/
@Deprecated
public void getMetrics(DisplayMetrics outMetrics) {