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."

Browse Source
This commit is contained in:
Jon Eckenrode
2022-03-23 14:16:19 +00:00
committed by Gerrit Code Review
parent cabb6b9362 25bfb7ef70
commit 7ac639b11b
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) {