Rename Display.getOrientation() to Display.getRotation().

Update various docs.

1 files changed, 42 insertions, 7 deletions

diff --git a/core/java/android/view/Display.java b/core/java/android/view/Display.java
index b055d51c1b40..ca7eec39eb75 100644
--- a/core/java/android/view/Display.java
+++ b/core/java/android/view/Display.java
@@ -45,41 +45,76 @@ public class Display
     }
     
     /**
-     * @return index of this display.
+     * Returns the index of this display.  This is currently undefined; do
+     * not use.
      */
     public int getDisplayId() {
         return mDisplay;
     }
 
     /**
-     * @return the number of displays connected to the device.
+     * Returns the number of displays connected to the device.  This is
+     * currently undefined; do not use.
      */
     native static int getDisplayCount();
     
     /**
-     * @return width of this display in pixels.
+     * Returns the raw width of the display, in pixels.  Note that this
+     * should <em>not</em> generally be used for computing layouts, since
+     * a device will typically have screen decoration (such as a status bar)
+     * along the edges of the display that reduce the amount of application
+     * space available from the raw size returned here.  This value is
+     * adjusted for you based on the current rotation of the display.
      */
     native public int getWidth();
     
     /**
-     * @return height of this display in pixels.
+     * Returns the raw height of the display, in pixels.  Note that this
+     * should <em>not</em> generally be used for computing layouts, since
+     * a device will typically have screen decoration (such as a status bar)
+     * along the edges of the display that reduce the amount of application
+     * space available from the raw size returned here.  This value is
+     * adjusted for you based on the current rotation of the display.
      */
     native public int getHeight();
 
     /**
+     * Returns the rotation of the screen from its "natural" orientation.
+     * The returned value may be {@link Surface#ROTATION_0 Surface.ROTATION_0}
+     * (no rotation), {@link Surface#ROTATION_90 Surface.ROTATION_90},
+     * {@link Surface#ROTATION_180 Surface.ROTATION_180}, or
+     * {@link Surface#ROTATION_270 Surface.ROTATION_270}.  For
+     * example, if a device has a naturally tall screen, and the user has
+     * turned it on its side to go into a landscape orientation, the value
+     * returned here may be either {@link Surface#ROTATION_90 Surface.ROTATION_90}
+     * or {@link Surface#ROTATION_270 Surface.ROTATION_270} depending on
+     * the direction it was turned.  The angle is the rotation of the drawn
+     * graphics on the screen, which is the opposite direction of the physical
+     * rotation of the device.  For example, if the device is rotated 90
+     * degrees counter-clockwise, to compensate rendering will be rotated by
+     * 90 degrees clockwise and thus the returned value here will be
+     * {@link Surface#ROTATION_90 Surface.ROTATION_90}.
+     */
+    public int getRotation() {
+        return getOrientation();
+    }
+    
+    /**
+     * @deprecated use
      * @return orientation of this display.
      */
-    native public int getOrientation();
+    @Deprecated native public int getOrientation();
 
     /**
-     * @return pixel format of this display.
+     * Return the native pixel format of the display.  The returned value
+     * may be one of the constants int {@link android.graphics.PixelFormat}.
      */
     public int getPixelFormat() {
         return mPixelFormat;
     }
     
     /**
-     * @return refresh rate of this display in frames per second.
+     * Return the refresh rate of this display in frames per second.
      */
     public float getRefreshRate() {
         return mRefreshRate;