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

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

Change-Id: I124703352d349e1c46ac13c6fdf50284af4b6be0
This commit is contained in:
Jon Eckenrode
2022-03-23 14:32:25 +00:00
committed by Automerger Merge Worker
parent 592bab637d 7ac639b11b
commit d3fd072f68
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. * 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>
* *
* @param outSize A {@link Point} object to receive the size information. * <p>The return value does not necessarily represent the actual size (native resolution) of the
* @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to obtain an instance of * display. The returned size might be adjusted to exclude certain system decor elements that
* {@link WindowMetrics} and use {@link WindowMetrics#getBounds()} instead. * 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 @Deprecated
public void getSize(Point outSize) { public void getSize(Point outSize) {
@@ -785,8 +792,9 @@ public final class Display {
* Gets the size of the display as a rectangle, in pixels. * Gets the size of the display as a rectangle, in pixels.
* *
* @param outSize A {@link Rect} object to receive the size information. * @param outSize A {@link Rect} object to receive the size information.
*
* @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application * @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application
* window area. * window.
*/ */
@Deprecated @Deprecated
public void getRectSize(Rect outSize) { 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. * Gets 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>The size returned does not necessarily represent the actual size (native resolution) of
* <p> * the display. The returned size might be adjusted to exclude certain system decor elements
* 1. The returned size may be adjusted to exclude certain system decor elements * that are always visible, or the size might be scaled to provide compatibility with older
* that are always visible. * applications that were originally designed for smaller displays.
* </p><p> *
* 2. It may be scaled to provide compatibility with older applications that * <p>The returned size can also be different depending on the WindowManager associated with the
* were originally designed for smaller displays. * display:
* </p><p> * <ul>
* 3. It can be different depending on the WindowManager to which the display belongs. * <li>If metrics are requested from an activity (either using a WindowManager accessed by
* </p><p> * {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the
* - If requested from non-Activity context (e.g. Application context via * returned metrics provide the size of the current app window. As a result, in
* {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}) * multi-window mode, the returned size can be smaller than the size of the device
* metrics will report the size of the entire display based on current rotation and with * screen.
* subtracted system decoration areas. * <li>If metrics are requested from a non-activity context (for example, the application
* </p><p> * context, where the WindowManager is accessed by
* - If requested from activity (either using {@code getWindowManager()} or * {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the
* {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting metrics will * returned size can vary depending on API level:
* correspond to current app window metrics. In this case the size can be smaller than physical * <ul>
* size in multi-window mode. * <li>API level 29 and below &mdash; The returned metrics provide the size of the
* </p> * 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 * @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 @Deprecated
public void getMetrics(DisplayMetrics outMetrics) { public void getMetrics(DisplayMetrics outMetrics) {