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

core/java/android/view/Display.java

+69 −54

Original line number	Original line	Diff line number	Diff line
	@@ -762,35 +762,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>The return value does not necessarily represent the actual size (native resolution) of the
	* <p>		* display. The returned size might be adjusted to exclude certain system decor elements that
	* 1. The returned size may be adjusted to exclude certain system decor elements		* 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 bound to 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 size is 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		* size of the current app window is returned. As a result, in multi-window mode, the
	* {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)})		* returned size can be smaller than the size of the device screen.
	* it will report the size of the entire display based on current rotation and with subtracted		* <li>If size is requested from a non-activity context (for example, the application
	* system decoration areas.		* context, where the WindowManager is accessed by
	* </p><p>		* {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the
	* - If requested from activity (either using {@code getWindowManager()} or		* returned size can vary depending on API level:
	* {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting size will		* <ul>
	* correspond to current app window size. In this case it can be smaller than physical size in		* <li>API level 29 and below — The size of the entire display (based on
	* multi-window mode.		* current rotation) minus system decoration areas is returned.
	* </p><p>		* <li>API level 30 and above — The size of the top running activity in the
	* Typically for the purposes of layout apps should make a request from activity context		* current process is returned. If the current process has no running
	* to obtain size available for the app content.		* activities, the size of the device default display, including system
	* </p>		* 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 WindowMetrics} instead. Obtain a {@code WindowMetrics} instance by
	* @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to obtain an instance of		* calling {@link WindowManager#getCurrentWindowMetrics()}, then call
	* {@link WindowMetrics} and use {@link WindowMetrics#getBounds()} instead.		* {@link WindowMetrics#getBounds()} to get the dimensions of the application window.
	*/		*/
	@Deprecated		@Deprecated
	public void getSize(Point outSize) {		public void getSize(Point outSize) {
	@@ -806,8 +813,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) {
	@@ -1379,32 +1387,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 — 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 — 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) {