Merge "Revised the API documentation of the getMetrics and getSize methods to... (7ac639b1) · Commits · e / os / android_frameworks_base

core/java/android/view/Display.java

+68 −53

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <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 — The size of the entire display (based on
		* current rotation) minus system decoration areas is returned.
		* <li>API level 30 and above — 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.
		*
		* @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.
		* @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 — The returned metrics provide the size of the
		* entire display (based on current rotation) minus system decoration areas.
		* <li>API level 30 and above — 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) {