Merge "Add APIs for an advanced print options activity." into klp-dev

6 files changed, 153 insertions, 2 deletions

diff --git a/api/current.txt b/api/current.txt
index abb330e96a56..ff48db0efdbe 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -267,6 +267,7 @@ package android {
     field public static final int addPrintersActivity = 16843750; // 0x10103e6
     field public static final int addStatesFromChildren = 16842992; // 0x10100f0
     field public static final int adjustViewBounds = 16843038; // 0x101011e
+    field public static final int advancedPrintOptionsActivity = 16843761; // 0x10103f1
     field public static final int alertDialogIcon = 16843605; // 0x1010355
     field public static final int alertDialogStyle = 16842845; // 0x101005d
     field public static final int alertDialogTheme = 16843529; // 0x1010309
@@ -19013,6 +19014,16 @@ package android.print {
     field public static final int STATE_STARTED = 3; // 0x3
   }
 
+  public static final class PrintJobInfo.Builder {
+    ctor public PrintJobInfo.Builder(android.print.PrintJobInfo);
+    method public android.print.PrintJobInfo build();
+    method public void putAdvancedOption(java.lang.String, java.lang.String);
+    method public void putAdvancedOption(java.lang.String, int);
+    method public void setAttributes(android.print.PrintAttributes);
+    method public void setCopies(int);
+    method public void setPages(android.print.PageRange[]);
+  }
+
   public final class PrintManager {
     method public java.util.List<android.print.PrintJob> getPrintJobs();
     method public android.print.PrintJob print(java.lang.String, android.print.PrintDocumentAdapter, android.print.PrintAttributes);
@@ -19095,10 +19106,13 @@ package android.printservice {
     method public boolean cancel();
     method public boolean complete();
     method public boolean fail(java.lang.String);
+    method public int getAdvancedIntOption(java.lang.String);
+    method public java.lang.String getAdvancedStringOption(java.lang.String);
     method public android.printservice.PrintDocument getDocument();
     method public android.print.PrintJobId getId();
     method public android.print.PrintJobInfo getInfo();
     method public java.lang.String getTag();
+    method public boolean hasAdvancedOption(java.lang.String);
     method public boolean isBlocked();
     method public boolean isCancelled();
     method public boolean isCompleted();
@@ -19120,6 +19134,7 @@ package android.printservice {
     method protected void onDisconnected();
     method protected abstract void onPrintJobQueued(android.printservice.PrintJob);
     method protected abstract void onRequestCancelPrintJob(android.printservice.PrintJob);
+    field public static final java.lang.String EXTRA_PRINT_JOB_INFO = "android.intent.extra.print.PRINT_JOB_INFO";
     field public static final java.lang.String SERVICE_INTERFACE = "android.printservice.PrintService";
     field public static final java.lang.String SERVICE_META_DATA = "android.printservice";
   }
diff --git a/core/java/android/print/PrintJobInfo.java b/core/java/android/print/PrintJobInfo.java
index 9f935c8311b1..c6f0a6848f91 100644
--- a/core/java/android/print/PrintJobInfo.java
+++ b/core/java/android/print/PrintJobInfo.java
@@ -439,7 +439,7 @@ public final class PrintJobInfo implements Parcelable {
     /**
      * Sets the included pages.
      *
-     * @return The included pages.
+     * @param pageRanges The included pages.
      *
      * @hide
      */
@@ -601,6 +601,81 @@ public final class PrintJobInfo implements Parcelable {
         }
     }
 
+    /**
+     * Builder for creating a {@link PrintJobInfo}.
+     */
+    public static final class Builder {
+        private final PrintJobInfo mPrototype;
+
+        /**
+         * Constructor.
+         *
+         * @param prototype Prototype to use as a starting point.
+         * Can be null.
+         */
+        public Builder(PrintJobInfo prototype) {
+            mPrototype = (prototype != null)
+                    ? new PrintJobInfo(prototype)
+                    : new PrintJobInfo();
+        }
+
+        /**
+         * Sets the number of copies.
+         *
+         * @param copies The number of copies.
+         */
+        public void setCopies(int copies) {
+            mPrototype.mCopies = copies;
+        }
+
+        /**
+         * Sets the print job attributes.
+         *
+         * @param attributes The attributes.
+         */
+        public void setAttributes(PrintAttributes attributes) {
+            mPrototype.mAttributes = attributes;
+        }
+
+        /**
+         * Sets the included pages.
+         *
+         * @param pages The included pages.
+         */
+        public void setPages(PageRange[] pages) {
+            mPrototype.mPageRanges = pages;
+        }
+
+        /**
+         * Puts an advanced (printer specific) option.
+         *
+         * @param key The option key.
+         * @param value The option value.
+         */
+        public void putAdvancedOption(String key, String value) {
+
+        }
+
+        /**
+         * Puts an advanced (printer specific) option.
+         *
+         * @param key The option key.
+         * @param value The option value.
+         */
+        public void putAdvancedOption(String key, int value) {
+
+        }
+
+        /**
+         * Creates a new {@link PrintJobInfo} instance.
+         *
+         * @return The new instance.
+         */
+        public PrintJobInfo build() {
+            return mPrototype;
+        }
+    }
+
     public static final Parcelable.Creator<PrintJobInfo> CREATOR =
             new Creator<PrintJobInfo>() {
         @Override
diff --git a/core/java/android/printservice/PrintJob.java b/core/java/android/printservice/PrintJob.java
index d1dbedf9ef63..fdeb3730b90e 100644
--- a/core/java/android/printservice/PrintJob.java
+++ b/core/java/android/printservice/PrintJob.java
@@ -304,7 +304,7 @@ public final class PrintJob {
     /**
      * Gets the print job tag.
      *
-     * @return tag The tag or null.
+     * @return The tag or null.
      *
      * @see #setTag(String)
      */
@@ -313,6 +313,40 @@ public final class PrintJob {
         return getInfo().getTag();
     }
 
+    /**
+     * Gets the value of an advanced (printer specific) print option.
+     *
+     * @param key The option key.
+     * @return The option value.
+     */
+    public String getAdvancedStringOption(String key) {
+        PrintService.throwIfNotCalledOnMainThread();
+        return null;
+    }
+
+    /**
+     * Gets whether this job has a given advanced (printer specific) print
+     * option.
+     *
+     * @param key The option key.
+     * @return Whether the option is present.
+     */
+    public boolean hasAdvancedOption(String key) {
+        PrintService.throwIfNotCalledOnMainThread();
+        return false;
+    }
+
+    /**
+     * Gets the value of an advanced (printer specific) print option.
+     *
+     * @param key The option key.
+     * @return The option value.
+     */
+    public int getAdvancedIntOption(String key) {
+        PrintService.throwIfNotCalledOnMainThread();
+        return 0;
+    }
+
     @Override
     public boolean equals(Object obj) {
         if (this == obj) {
diff --git a/core/java/android/printservice/PrintService.java b/core/java/android/printservice/PrintService.java
index e73a53bee819..0fc5f7f035a6 100644
--- a/core/java/android/printservice/PrintService.java
+++ b/core/java/android/printservice/PrintService.java
@@ -16,6 +16,7 @@
 
 package android.printservice;
 
+import android.R;
 import android.app.Service;
 import android.content.ComponentName;
 import android.content.Context;
@@ -189,6 +190,28 @@ public abstract class PrintService extends Service {
      */
     public static final String SERVICE_META_DATA = "android.printservice";
 
+    /**
+     * If you declared an optional activity with advanced print options via the
+     * {@link R.attr#advancedPrintOptionsActivity advancedPrintOptionsActivity}
+     * attribute, this extra is used to pass in the currently constructed {@link
+     * PrintJobInfo} to your activity allowing you to modify it. After you are
+     * done, you must return the modified {@link PrintJobInfo} via the same extra.
+     * <p>
+     * You cannot modify the passed in {@link PrintJobInfo} directly, rather you
+     * should build another one using the {@link PrintJobInfo.Builder} class. You
+     * can specify any standard properties and add advanced, printer specific,
+     * ones via {@link PrintJobInfo.Builder#putAdvancedOption(String, String)
+     * PrintJobInfo.Builder#putAdvancedOption(String, String)} and {@link
+     * PrintJobInfo.Builder#putAdvancedOption(String, int)
+     * PrintJobInfo.Builder#putAdvancedOption(String, int)}. The advanced options
+     * are not interpreted by the system, they will not be visible to applications,
+     * and can only be accessed by your print service via {@link
+     * PrintJob#getAdvancedStringOption(String) PrintJob.getAdvancedStringOption(String)}
+     * and {@link PrintJob#getAdvancedIntOption(String) PrintJob.getAdvancedIntOption(String)}.
+     * </p>
+     */
+    public static final String EXTRA_PRINT_JOB_INFO = "android.intent.extra.print.PRINT_JOB_INFO";
+
     private Handler mHandler;
 
     private IPrintServiceClient mClient;
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 9ee8baeb5afb..42e3b50376c8 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -2621,6 +2621,9 @@
         <!-- Fully qualified class name of an activity that allows the user to manually
              add printers to this print service. -->
         <attr name="addPrintersActivity" format="string"/>
+        <!-- Fully qualified class name of an activity with advanced print options
+             specific to this print service. -->
+        <attr name="advancedPrintOptionsActivity" format="string"/>
         <!-- The vendor name if this print service is vendor specific. -->
         <attr name="vendor" format="string"/>
     </declare-styleable>
diff --git a/core/res/res/values/public.xml b/core/res/res/values/public.xml
index 463573375651..81879392c222 100644
--- a/core/res/res/values/public.xml
+++ b/core/res/res/values/public.xml
@@ -2080,6 +2080,7 @@
   <public type="attr" name="accessibilityLiveRegion" id="0x010103ee" />
   <public type="attr" name="windowTranslucentStatus" id="0x010103ef" />
   <public type="attr" name="windowTranslucentNavigation" id="0x010103f0" />
+  <public type="attr" name="advancedPrintOptionsActivity" id="0x10103f1"/>
 
   <public type="style" name="Theme.Holo.NoActionBar.TranslucentDecor" id="0x010301e1" />
   <public type="style" name="Theme.Holo.Light.NoActionBar.TranslucentDecor" id="0x010301e2" />