am 23ef7b48: Fix most of issue #2271640: Fix wallpaper etc docs

Merge commit '23ef7b4836d66d31430fedee2aac36275bb30d4b' into eclair-plus-aosp

* commit '23ef7b4836d66d31430fedee2aac36275bb30d4b':
  Fix most of issue #2271640: Fix wallpaper etc docs

9 files changed, 149 insertions, 117 deletions

diff --git a/api/current.xml b/api/current.xml
index 81cb646..6650015 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -1934,6 +1934,17 @@
  visibility="public"
 >
 </field>
+<field name="author"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="16843444"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 <field name="authorities"
  type="int"
  transient="false"
@@ -1971,7 +1982,7 @@
  type="int"
  transient="false"
  volatile="false"
- value="16843446"
+ value="16843445"
  static="true"
  final="true"
  deprecated="not deprecated"
@@ -8853,17 +8864,6 @@
  visibility="public"
 >
 </field>
-<field name="wallpaperAuthor"
- type="int"
- transient="false"
- volatile="false"
- value="16843444"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
 <field name="wallpaperCloseEnterAnimation"
  type="int"
  transient="false"
@@ -8886,17 +8886,6 @@
  visibility="public"
 >
 </field>
-<field name="wallpaperDescription"
- type="int"
- transient="false"
- volatile="false"
- value="16843445"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
 <field name="wallpaperIntraCloseEnterAnimation"
  type="int"
  transient="false"
@@ -25166,6 +25155,28 @@
  visibility="public"
 >
 </field>
+<field name="COMMAND_DROP"
+ type="java.lang.String"
+ transient="false"
+ volatile="false"
+ value="&quot;android.home.drop&quot;"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="COMMAND_TAP"
+ type="java.lang.String"
+ transient="false"
+ volatile="false"
+ value="&quot;android.wallpaper.tap&quot;"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 </class>
 </package>
 <package name="android.appwidget"
@@ -99872,6 +99883,17 @@
  visibility="public"
 >
 </field>
+<field name="ECLAIR_MR1"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="7"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 </class>
 <class name="Bundle"
  extends="java.lang.Object"
@@ -123817,34 +123839,6 @@
 </parameter>
 </method>
 </class>
-<class name="WallpaperSettingsActivity"
- extends="android.preference.PreferenceActivity"
- abstract="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<constructor name="WallpaperSettingsActivity"
- type="android.service.wallpaper.WallpaperSettingsActivity"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</constructor>
-<field name="EXTRA_PREVIEW_MODE"
- type="java.lang.String"
- transient="false"
- volatile="false"
- value="&quot;android.service.wallpaper.PREVIEW_MODE&quot;"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-</class>
 </package>
 <package name="android.speech"
 >
diff --git a/core/java/android/app/WallpaperInfo.java b/core/java/android/app/WallpaperInfo.java
index 34d3133..1034fab 100644
--- a/core/java/android/app/WallpaperInfo.java
+++ b/core/java/android/app/WallpaperInfo.java
@@ -101,10 +101,10 @@ public final class WallpaperInfo implements Parcelable {
                     com.android.internal.R.styleable.Wallpaper_thumbnail,
                     -1);
             authorRes = sa.getResourceId(
-                    com.android.internal.R.styleable.Wallpaper_wallpaperAuthor,
+                    com.android.internal.R.styleable.Wallpaper_author,
                     -1);
             descriptionRes = sa.getResourceId(
-                    com.android.internal.R.styleable.Wallpaper_wallpaperDescription,
+                    com.android.internal.R.styleable.Wallpaper_description,
                     -1);
 
             sa.recycle();
diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java
index f606346..e455a59 100644
--- a/core/java/android/app/WallpaperManager.java
+++ b/core/java/android/app/WallpaperManager.java
@@ -63,6 +63,21 @@ public class WallpaperManager {
     public static final String ACTION_LIVE_WALLPAPER_CHOOSER
             = "android.service.wallpaper.LIVE_WALLPAPER_CHOOSER";
     
+    /**
+     * Command for {@link #sendWallpaperCommand}: reported by the wallpaper
+     * host when the user taps on an empty area (not performing an action
+     * in the host).  The x and y arguments are the location of the tap in
+     * screen coordinates.
+     */
+    public static final String COMMAND_TAP = "android.wallpaper.tap";
+    
+    /**
+     * Command for {@link #sendWallpaperCommand}: reported by the wallpaper
+     * host when the user drops an object into an area of the host.  The x
+     * and y arguments are the location of the drop.
+     */
+    public static final String COMMAND_DROP = "android.home.drop";
+    
     private final Context mContext;
     
     /**
@@ -604,7 +619,7 @@ public class WallpaperManager {
     /**
      * For applications that use multiple virtual screens showing a wallpaper,
      * specify the step size between virtual screens. For example, if the
-     * launcher has 5 virtual screens, it would specify an xStep of 0.5,
+     * launcher has 3 virtual screens, it would specify an xStep of 0.5,
      * since the X offset for those screens are 0.0, 0.5 and 1.0
      * @param xStep The X offset delta from one screen to the next one 
      * @param yStep The Y offset delta from one screen to the next one
diff --git a/core/java/android/os/Build.java b/core/java/android/os/Build.java
index ee18e88..e9353d8 100644
--- a/core/java/android/os/Build.java
+++ b/core/java/android/os/Build.java
@@ -161,6 +161,11 @@ public class Build {
          * December 2009: Android 2.0.1
          */
         public static final int ECLAIR_0_1 = 6;
+        
+        /**
+         * January 2010: Android 2.1
+         */
+        public static final int ECLAIR_MR1 = 7;
     }
     
     /** The type of build, like "user" or "eng". */
diff --git a/core/java/android/service/wallpaper/WallpaperService.java b/core/java/android/service/wallpaper/WallpaperService.java
index b29d837..8000ad3 100644
--- a/core/java/android/service/wallpaper/WallpaperService.java
+++ b/core/java/android/service/wallpaper/WallpaperService.java
@@ -46,7 +46,12 @@ import android.view.WindowManagerImpl;
 
 /**
  * A wallpaper service is responsible for showing a live wallpaper behind
- * applications that would like to sit on top of it.
+ * applications that would like to sit on top of it.  This service object
+ * itself does very little -- its only purpose is to generate instances of
+ * {@link WallpaperSerice.Engine} as needed.  Implementing a wallpaper thus
+ * involves subclassing from this, subclassing an Engine implementation,
+ * and implementing {@link #onCreateEngine()} to return a new instance of
+ * your engine.
  */
 public abstract class WallpaperService extends Service {
     /**
@@ -861,5 +866,11 @@ public abstract class WallpaperService extends Service {
         mCallbackLooper = looper;
     }
     
+    /**
+     * Must be implemented to return a new instance of the wallpaper's engine.
+     * Note that multiple instances may be active at the same time, such as
+     * when the wallpaper is currently set as the active wallpaper and the user
+     * is in the wallpaper picker viewing a preview of it as well.
+     */
     public abstract Engine onCreateEngine();
 }
diff --git a/core/java/android/service/wallpaper/WallpaperSettingsActivity.java b/core/java/android/service/wallpaper/WallpaperSettingsActivity.java
index 501947d..aca336f 100644
--- a/core/java/android/service/wallpaper/WallpaperSettingsActivity.java
+++ b/core/java/android/service/wallpaper/WallpaperSettingsActivity.java
@@ -24,6 +24,7 @@ import android.preference.PreferenceActivity;
  * Base class for activities that will be used to configure the settings of
  * a wallpaper.  You should derive from this class to allow it to select the
  * proper theme of the activity depending on how it is being used.
+ * @hide
  */
 public class WallpaperSettingsActivity extends PreferenceActivity {
     /**
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 9d1b2c8..68661ae 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -3482,11 +3482,11 @@
         <!-- Reference to a the wallpaper's thumbnail bitmap. -->
         <attr name="thumbnail" format="reference" />
 
-        <!-- Name of the author of a wallpaper, e.g. Google. -->
-        <attr name="wallpaperAuthor" format="reference" />
+        <!-- Name of the author of this component, e.g. Google. -->
+        <attr name="author" format="reference" />
 
-        <!-- Short description of the wallpaper's purpose or behavior. -->
-        <attr name="wallpaperDescription" format="reference" />
+        <!-- Short description of the component's purpose or behavior. -->
+        <attr name="description" />
     </declare-styleable>
 
     <!-- =============================== -->
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 4a3da11..62529f1 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -528,11 +528,7 @@
         <flag name="fontScale" value="0x40000000" />
     </attr>
     
-    <!-- A longer descriptive text about a particular application or
-         permission that can be granted.  This must be a reference 
-         to a string resource; unlike
-    	 the {@link android.R.attr#label} attribute, this can not be a
-    	 raw string. -->
+    <!-- Descriptive text for the associated data. -->
     <attr name="description" format="reference" />
     
     <!-- The name of the application package that an Instrumentation object
diff --git a/core/res/res/values/public.xml b/core/res/res/values/public.xml
index 4ede620..311930a 100644
--- a/core/res/res/values/public.xml
+++ b/core/res/res/values/public.xml
@@ -933,7 +933,7 @@
   <public type="attr" name="marqueeRepeatLimit" id="0x0101021d" />
 
 <!-- ===============================================================
-     Resources added in version 3 of the platform.
+     Resources added in version 3 of the platform (Cupcake).
      =============================================================== -->
   <eat-comment />
 
@@ -1087,7 +1087,7 @@
   <public type="integer" name="config_longAnimTime" id="0x010e0002" />
 
 <!-- ===============================================================
-     Resources added in Donut.
+     Resources added in version 4 of the platform (Donut).
      =============================================================== -->
   <eat-comment />
 
@@ -1142,67 +1142,77 @@
   <public type="anim" name="linear_interpolator" id="0x010a000b" />
 
 <!-- ===============================================================
-     Resources added in Eclair.
+     Resources added in version 5 of the platform (Eclair).
      =============================================================== -->
   <eat-comment />
 
   <public type="attr" name="required" id="0x0101028e" />
-  <public type="attr" name="accountType" />
-  <public type="attr" name="contentAuthority" />
-  <public type="attr" name="userVisible" />
-  <public type="attr" name="windowShowWallpaper" />
-  <public type="attr" name="wallpaperOpenEnterAnimation" />
-  <public type="attr" name="wallpaperOpenExitAnimation" />
-  <public type="attr" name="wallpaperCloseEnterAnimation" />
-  <public type="attr" name="wallpaperCloseExitAnimation" />
-  <public type="attr" name="wallpaperIntraOpenEnterAnimation" />
-  <public type="attr" name="wallpaperIntraOpenExitAnimation" />
-  <public type="attr" name="wallpaperIntraCloseEnterAnimation" />
-  <public type="attr" name="wallpaperIntraCloseExitAnimation" />
-  <public type="attr" name="supportsUploading" />
-  <public type="attr" name="killAfterRestore" />
-  <public type="attr" name="restoreNeedsApplication" />
-  <public type="attr" name="smallIcon" />
-  <public type="attr" name="accountPreferences" />
-  <public type="attr" name="textAppearanceSearchResultSubtitle" />
-  <public type="attr" name="textAppearanceSearchResultTitle" />
-  <public type="attr" name="summaryColumn" />
-  <public type="attr" name="detailColumn" />
-  <public type="attr" name="detailSocialSummary" />
-  <public type="attr" name="thumbnail" />
-  <public type="attr" name="detachWallpaper" />
-  <public type="attr" name="finishOnCloseSystemDialogs" />
-  <public type="attr" name="scrollbarFadeDuration" />
-  <public type="attr" name="scrollbarDefaultDelayBeforeFade" />
-  <public type="attr" name="fadeScrollbars" />
-  <public type="attr" name="colorBackgroundCacheHint" />
-  <public type="attr" name="dropDownHorizontalOffset" />
-  <public type="attr" name="dropDownVerticalOffset" />
+  <public type="attr" name="accountType" id="0x0101028f" />
+  <public type="attr" name="contentAuthority" id="0x01010290" />
+  <public type="attr" name="userVisible" id="0x01010291" />
+  <public type="attr" name="windowShowWallpaper" id="0x01010292" />
+  <public type="attr" name="wallpaperOpenEnterAnimation" id="0x01010293" />
+  <public type="attr" name="wallpaperOpenExitAnimation" id="0x01010294" />
+  <public type="attr" name="wallpaperCloseEnterAnimation" id="0x01010295" />
+  <public type="attr" name="wallpaperCloseExitAnimation" id="0x01010296" />
+  <public type="attr" name="wallpaperIntraOpenEnterAnimation" id="0x01010297" />
+  <public type="attr" name="wallpaperIntraOpenExitAnimation" id="0x01010298" />
+  <public type="attr" name="wallpaperIntraCloseEnterAnimation" id="0x01010299" />
+  <public type="attr" name="wallpaperIntraCloseExitAnimation" id="0x0101029a" />
+  <public type="attr" name="supportsUploading" id="0x0101029b" />
+  <public type="attr" name="killAfterRestore" id="0x0101029c" />
+  <public type="attr" name="restoreNeedsApplication" id="0x0101029d" />
+  <public type="attr" name="smallIcon" id="0x0101029e" />
+  <public type="attr" name="accountPreferences" id="0x0101029f" />
+  <public type="attr" name="textAppearanceSearchResultSubtitle" id="0x010102a0" />
+  <public type="attr" name="textAppearanceSearchResultTitle" id="0x010102a1" />
+  <public type="attr" name="summaryColumn" id="0x010102a2" />
+  <public type="attr" name="detailColumn" id="0x010102a3" />
+  <public type="attr" name="detailSocialSummary" id="0x010102a4" />
+  <public type="attr" name="thumbnail" id="0x010102a5" />
+  <public type="attr" name="detachWallpaper" id="0x010102a6" />
+  <public type="attr" name="finishOnCloseSystemDialogs" id="0x010102a7" />
+  <public type="attr" name="scrollbarFadeDuration" id="0x010102a8" />
+  <public type="attr" name="scrollbarDefaultDelayBeforeFade" id="0x010102a9" />
+  <public type="attr" name="fadeScrollbars" id="0x010102aa" />
+  <public type="attr" name="colorBackgroundCacheHint" id="0x010102ab" />
+  <public type="attr" name="dropDownHorizontalOffset" id="0x010102ac" />
+  <public type="attr" name="dropDownVerticalOffset" id="0x010102ad" />
   
-  <public type="style" name="Theme.Wallpaper" />
-  <public type="style" name="Theme.Wallpaper.NoTitleBar" />
-  <public type="style" name="Theme.Wallpaper.NoTitleBar.Fullscreen" />
-  <public type="style" name="Theme.WallpaperSettings" />
-  <public type="style" name="Theme.Light.WallpaperSettings" />
-  <public type="style" name="TextAppearance.SearchResult.Title" />
-  <public type="style" name="TextAppearance.SearchResult.Subtitle" />
+  <public type="style" name="Theme.Wallpaper" id="0x0103005e" />
+  <public type="style" name="Theme.Wallpaper.NoTitleBar" id="0x0103005f" />
+  <public type="style" name="Theme.Wallpaper.NoTitleBar.Fullscreen" id="0x01030060" />
+  <public type="style" name="Theme.WallpaperSettings" id="0x01030061" />
+  <public type="style" name="Theme.Light.WallpaperSettings" id="0x01030062" />
+  <public type="style" name="TextAppearance.SearchResult.Title" id="0x01030063" />
+  <public type="style" name="TextAppearance.SearchResult.Subtitle" id="0x01030064" />
   
   <!-- Semi-transparent background that can be used when placing a dark
        themed UI on top of some arbitrary background (such as the
        wallpaper).  This darkens the background sufficiently that the UI
        can be seen. -->
-  <public type="drawable" name="screen_background_dark_transparent" />
-  <public type="drawable" name="screen_background_light_transparent" />
-  <public type="drawable" name="stat_notify_sdcard_prepare" />
+  <public type="drawable" name="screen_background_dark_transparent" id="0x010800a9" />
+  <public type="drawable" name="screen_background_light_transparent" id="0x010800aa" />
+  <public type="drawable" name="stat_notify_sdcard_prepare" id="0x010800ab" />
   
-  <public type="attr" name="quickContactBadgeStyleWindowSmall" />
-  <public type="attr" name="quickContactBadgeStyleWindowMedium" />
-  <public type="attr" name="quickContactBadgeStyleWindowLarge" />
-  <public type="attr" name="quickContactBadgeStyleSmallWindowSmall" />
-  <public type="attr" name="quickContactBadgeStyleSmallWindowMedium" />
-  <public type="attr" name="quickContactBadgeStyleSmallWindowLarge" />
-  <public type="attr" name="wallpaperAuthor" />
-  <public type="attr" name="wallpaperDescription" />
-  <public type="attr" name="autoStart" />
+<!-- ===============================================================
+     Resources added in version 6 of the platform (Eclair 2.0.1).
+     =============================================================== -->
+  <eat-comment />
+
+  <public type="attr" name="quickContactBadgeStyleWindowSmall" id="0x010102ae" />
+  <public type="attr" name="quickContactBadgeStyleWindowMedium" id="0x010102af" />
+  <public type="attr" name="quickContactBadgeStyleWindowLarge" id="0x010102b0" />
+  <public type="attr" name="quickContactBadgeStyleSmallWindowSmall" id="0x010102b1" />
+  <public type="attr" name="quickContactBadgeStyleSmallWindowMedium" id="0x010102b2" />
+  <public type="attr" name="quickContactBadgeStyleSmallWindowLarge" id="0x010102b3" />
+  
+<!-- ===============================================================
+     Resources added in version 7 of the platform (Eclair MR1).
+     =============================================================== -->
+  <eat-comment />
+
+  <public type="attr" name="author" id="0x010102b4" />
+  <public type="attr" name="autoStart" id="0x010102b5" />
   
 </resources>