Merge "add links to orientation flags in attribute docs to help determine the supported API level for each value and update the manifest reference page with new attributes" into jb-mr2-dev

2 files changed, 81 insertions, 22 deletions

diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index f2c0aa0d2396..e7f6c53e27ee 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -547,7 +547,10 @@
     
     <!-- Specify the orientation an activity should be run in.  If not
          specified, it will run in the current preferred orientation
-         of the screen. -->
+         of the screen.
+         <p>This attribute is supported by the <a
+            href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity>}</a>
+            element. -->
     <attr name="screenOrientation">
         <!-- No preference specified: let the system decide the best
              orientation.  This will either be the orientation selected
@@ -556,59 +559,91 @@
              explicitly turned off sensor based orientation through settings
              sensor based device rotation will be ignored. If not by default
              sensor based orientation will be taken into account and the 
-             orientation will changed based on how the user rotates the device -->
+             orientation will changed based on how the user rotates the device.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_UNSPECIFIED}. -->
         <enum name="unspecified" value="-1" />
         <!-- Would like to have the screen in a landscape orientation: that
-             is, with the display wider than it is tall, ignoring sensor data. -->
+             is, with the display wider than it is tall, ignoring sensor data.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}. -->
         <enum name="landscape" value="0" />
         <!-- Would like to have the screen in a portrait orientation: that
-             is, with the display taller than it is wide, ignoring sensor data. -->
+             is, with the display taller than it is wide, ignoring sensor data.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_PORTRAIT}. -->
         <enum name="portrait" value="1" />
-        <!-- Use the user's current preferred orientation of the handset. -->
+        <!-- Use the user's current preferred orientation of the handset.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_USER}. -->
         <enum name="user" value="2" />
         <!-- Keep the screen in the same orientation as whatever is behind
-             this activity. -->
+             this activity.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_BEHIND}. -->
         <enum name="behind" value="3" />
         <!-- Orientation is determined by a physical orientation sensor:
              the display will rotate based on how the user moves the device.
-             Ignores user's setting to turn off sensor-based rotation. -->
+             Ignores user's setting to turn off sensor-based rotation.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_SENSOR}. -->
         <enum name="sensor" value="4" />
         <!-- Always ignore orientation determined by orientation sensor:
-             the display will not rotate when the user moves the device. -->
+             the display will not rotate when the user moves the device.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_NOSENSOR}. -->
         <enum name="nosensor" value="5" />
         <!-- Would like to have the screen in landscape orientation, but can
-             use the sensor to change which direction the screen is facing. -->
+             use the sensor to change which direction the screen is facing.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_SENSOR_LANDSCAPE}. -->
         <enum name="sensorLandscape" value="6" />
         <!-- Would like to have the screen in portrait orientation, but can
-             use the sensor to change which direction the screen is facing. -->
+             use the sensor to change which direction the screen is facing.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_SENSOR_PORTRAIT}. -->
         <enum name="sensorPortrait" value="7" />
         <!-- Would like to have the screen in landscape orientation, turned in
-             the opposite direction from normal landscape. -->
+             the opposite direction from normal landscape.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_REVERSE_LANDSCAPE}. -->
         <enum name="reverseLandscape" value="8" />
         <!-- Would like to have the screen in portrait orientation, turned in
-             the opposite direction from normal portrait. -->
+             the opposite direction from normal portrait.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_REVERSE_PORTRAIT}. -->
         <enum name="reversePortrait" value="9" />
         <!-- Orientation is determined by a physical orientation sensor:
              the display will rotate based on how the user moves the device.
              This allows any of the 4 possible rotations, regardless of what
              the device will normally do (for example some devices won't
-             normally use 180 degree rotation). -->
+             normally use 180 degree rotation).
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_FULL_SENSOR}. -->
         <enum name="fullSensor" value="10" />
         <!-- Would like to have the screen in landscape orientation, but if
              the user has enabled sensor-based rotation then we can use the
-             sensor to change which direction the screen is facing. -->
+             sensor to change which direction the screen is facing.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_USER_LANDSCAPE}. -->
         <enum name="userLandscape" value="11" />
         <!-- Would like to have the screen in portrait orientation, but if
              the user has enabled sensor-based rotation then we can use the
-             sensor to change which direction the screen is facing. -->
+             sensor to change which direction the screen is facing.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_USER_PORTRAIT}. -->
         <enum name="userPortrait" value="12" />
         <!-- Respect the user's sensor-based rotation preference, but if
              sensor-based rotation is enabled then allow the screen to rotate
              in all 4 possible directions regardless of what
              the device will normally do (for example some devices won't
-             normally use 180 degree rotation). -->
+             normally use 180 degree rotation).
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_FULL_USER}. -->
         <enum name="fullUser" value="13" />
-        <!-- Screen is locked to its current rotation, whatever that is. -->
+        <!-- Screen is locked to its current rotation, whatever that is.
+             Corresponds to
+             {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LOCKED}. -->
         <enum name="locked" value="14" />
     </attr>
     
diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd
index c9f505f3b8a7..adc795d6437f 100644
--- a/docs/html/guide/topics/manifest/activity-element.jd
+++ b/docs/html/guide/topics/manifest/activity-element.jd
@@ -27,11 +27,13 @@ parent.link=manifest-intro.html
           android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 -->
           android:<a href="#prmsn">permission</a>="<i>string</i>"
           android:<a href="#proc">process</a>="<i>string</i>"
-          android:<a href="#screen">screenOrientation</a>=["unspecified" | "user" | "behind" |
+          android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" |
                                      "landscape" | "portrait" |
                                      "reverseLandscape" | "reversePortrait" |
                                      "sensorLandscape" | "sensorPortrait" |
-                                     "sensor" | "fullSensor" | "nosensor"]
+                                     "userLandscape" | "userPortrait" |
+                                     "sensor" | "fullSensor" | "nosensor" |
+                                     "user" | "fullUser" | "locked"]
           android:<a href="#state">stateNotNeeded</a>=["true" | "false"]
           android:<a href="#aff">taskAffinity</a>="<i>string</i>"
           android:<a href="#theme">theme</a>="<i>resource or theme</i>"
@@ -644,9 +646,6 @@ resource usage.
        uses, and therefore the choices made in specific contexts, may differ 
        from device to device.</td>
 </tr><tr>
-   <td>"{@code user}"</td>
-   <td>The user's current preferred orientation.</td>
-</tr><tr>
    <td>"{@code behind}"</td>
    <td>The same orientation as the activity that's immediately beneath it in 
        the activity stack.</td>
@@ -675,6 +674,18 @@ sensor.
 sensor.
 <em>Added in API level 9.</em></td>
 </tr><tr>
+   <td>"{@code userLandscape}"</td>
+   <td>Landscape orientation, but can be either normal or reverse landscape based on the device
+sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves
+the same as {@code landscape}, otherwise it behaves the same as {@code sensorLandscape}.
+<em>Added in API level 18.</em></td>
+</tr><tr>
+   <td>"{@code userPortrait}"</td>
+   <td>Portrait orientation, but can be either normal or reverse portrait based on the device
+sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves
+the same as {@code portrait}, otherwise it behaves the same as {@code sensorPortrait}.
+<em>Added in API level 18.</em></td>
+</tr><tr>
    <td>"{@code sensor}"</td>
    <td>The orientation is determined by the device orientation sensor.  The orientation of the
 display depends on how the user is holding the device; it changes when the user rotates the
@@ -692,6 +703,19 @@ portrait or reverse landscape, but this enables those). <em>Added in API level 9
 is ignored, so the display will not rotate based on how the user moves the device.  Except for this
 distinction, the system chooses the orientation using the same policy as for the "{@code
 unspecified}" setting.</td>
+</tr><tr>
+   <td>"{@code user}"</td>
+   <td>The user's current preferred orientation.</td>
+</tr><tr>
+   <td>"{@code fullUser}"</td>
+   <td>If the user has locked sensor-based rotation, this behaves the same as {@code user},
+   otherwise it behaves the same as {@code fullSensor} and allows any of the 4 possible
+   screen orientations.
+    <em>Added in API level 18.</em></td>
+</tr><tr>
+   <td>"{@code locked}"</td>
+   <td>Locks the orientation to its current rotation, whatever that is.
+<em>Added in API level 18.</em></td>
 </tr>
 </table>