public final class PrintManager extends Object
To obtain a handle to the print manager do the following:
PrintManager printManager = (PrintManager) context.getSystemService(Context.PRINT_SERVICE);
The key idea behind printing on the platform is that the content to be printed
should be laid out for the currently selected print options resulting in an
optimized output and higher user satisfaction. To achieve this goal the platform
declares a contract that the printing application has to follow which is defined
by the PrintDocumentAdapter
class. At a higher level the contract is that
when the user selects some options from the print UI that may affect the way
content is laid out, for example page size, the application receives a callback
allowing it to layout the content to better fit these new constraints. After a
layout pass the system may ask the application to render one or more pages one
or more times. For example, an application may produce a single column list for
smaller page sizes and a multi-column table for larger page sizes.
Print jobs are started by calling the print(String, PrintDocumentAdapter,
PrintAttributes)
from an activity which results in bringing up the system print
UI. Once the print UI is up, when the user changes a selected print option that
affects the way content is laid out the system starts to interact with the
application following the mechanics described the section above.
Print jobs can be in created
, queued
, started
,
blocked
, completed
, failed
, and canceled
state. Print jobs are stored in dedicated
system spooler until they are handled which is they are cancelled or completed.
Active print jobs, ones that are not cancelled or completed, are considered failed
if the device reboots as the new boot may be after a very long time. The user may
choose to restart such print jobs. Once a print job is queued all relevant content
is stored in the system spooler and its lifecycle becomes detached from this of
the application that created it.
An applications can query the print spooler for current print jobs it created but not print jobs created by other applications.
PrintJob
,
PrintJobInfo
Modifier and Type | Class and Description |
---|---|
static class |
PrintManager.PrintDocumentAdapterDelegate |
static interface |
PrintManager.PrintJobStateChangeListener |
static class |
PrintManager.PrintJobStateChangeListenerWrapper |
static interface |
PrintManager.PrintServiceRecommendationsChangeListener |
static class |
PrintManager.PrintServiceRecommendationsChangeListenerWrapper |
static interface |
PrintManager.PrintServicesChangeListener |
static class |
PrintManager.PrintServicesChangeListenerWrapper |
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_PRINT_DIALOG
The action for launching the print dialog activity.
|
static int |
ALL_SERVICES
Select all services.
|
static int |
APP_ID_ANY |
static int |
DISABLED_SERVICES
Select disabled services.
|
static int |
ENABLED_SERVICES
Select enabled services.
|
static String |
EXTRA_PRINT_DIALOG_INTENT
Extra with the intent for starting the print dialog.
|
static String |
EXTRA_PRINT_DOCUMENT_ADAPTER
Extra with the print document adapter to be printed.
|
static String |
EXTRA_PRINT_JOB
Extra with a print job.
|
static String |
PRINT_SPOOLER_PACKAGE_NAME
Package name of print spooler.
|
Constructor and Description |
---|
PrintManager(Context context,
IPrintManager service,
int userId,
int appId)
Creates a new instance.
|
Modifier and Type | Method and Description |
---|---|
void |
addPrintJobStateChangeListener(PrintManager.PrintJobStateChangeListener listener)
Adds a listener for observing the state of print jobs.
|
PrinterDiscoverySession |
createPrinterDiscoverySession() |
Icon |
getCustomPrinterIcon(PrinterId printerId)
Get the custom icon for a printer.
|
PrintManager |
getGlobalPrintManagerForUser(int userId)
Creates an instance that can access all print jobs.
|
PrintJob |
getPrintJob(PrintJobId printJobId)
Gets a print job given its id.
|
List<PrintJob> |
getPrintJobs()
Gets the print jobs for this application.
|
List<RecommendationInfo> |
getPrintServiceRecommendations()
Gets the list of print service recommendations, but does not register for updates.
|
List<PrintServiceInfo> |
getPrintServices(int selectionFlags)
Gets the list of print services, but does not register for updates.
|
PrintJob |
print(String printJobName,
PrintDocumentAdapter documentAdapter,
PrintAttributes attributes)
Creates a print job for printing a
PrintDocumentAdapter with
default print attributes. |
void |
removePrintJobStateChangeListener(PrintManager.PrintJobStateChangeListener listener)
Removes a listener for observing the state of print jobs.
|
void |
setPrintServiceEnabled(ComponentName service,
boolean isEnabled)
Enable or disable a print service.
|
public static final String PRINT_SPOOLER_PACKAGE_NAME
public static final int ENABLED_SERVICES
getPrintServices(int)
,
Constant Field Valuespublic static final int DISABLED_SERVICES
getPrintServices(int)
,
Constant Field Valuespublic static final int ALL_SERVICES
getPrintServices(int)
,
Constant Field Valuespublic static final String ACTION_PRINT_DIALOG
public static final String EXTRA_PRINT_DIALOG_INTENT
Type: IntentSender
public static final String EXTRA_PRINT_JOB
Type: PrintJobInfo
public static final String EXTRA_PRINT_DOCUMENT_ADAPTER
Type: android.print.IPrintDocumentAdapter
public static final int APP_ID_ANY
public PrintManager(Context context, IPrintManager service, int userId, int appId)
context
- The current context in which to operate.service
- The backing system service.userId
- The user id in which to operate.appId
- The application id in which to operate.public PrintManager getGlobalPrintManagerForUser(int userId)
userId
- The user id for which to get all print jobs.public void addPrintJobStateChangeListener(PrintManager.PrintJobStateChangeListener listener)
listener
- The listener to add.public void removePrintJobStateChangeListener(PrintManager.PrintJobStateChangeListener listener)
listener
- The listener to remove.public PrintJob getPrintJob(PrintJobId printJobId)
printJobId
- The id of the print job.PrintJob
public Icon getCustomPrinterIcon(PrinterId printerId)
printerId
- the id of the printer the icon should be loaded forandroid.print.PrinterInfo.Builder#setHasCustomPrinterIcon()
public List<PrintJob> getPrintJobs()
PrintJob
public PrintJob print(String printJobName, PrintDocumentAdapter documentAdapter, PrintAttributes attributes)
PrintDocumentAdapter
with
default print attributes.
Calling this method brings the print UI allowing the user to customize
the print job and returns a PrintJob
object without waiting for the
user to customize or confirm the print job. The returned print job instance
is in a created
state.
This method can be called only from an Activity
. The rationale is that
printing from a service will create an inconsistent user experience as the print
UI would appear without any context.
Also the passed in PrintDocumentAdapter
will be considered invalid if
your activity is finished. The rationale is that once the activity that
initiated printing is finished, the provided adapter may be in an inconsistent
state as it may depend on the UI presented by the activity.
The default print attributes are a hint to the system how the data is to be printed. For example, a photo editor may look at the photo aspect ratio to determine the default orientation and provide a hint whether the printing should be in portrait or landscape. The system will do a best effort to selected the hinted options in the print dialog, given the current printer supports them.
Note: Calling this method will bring the print dialog and
the system will connect to the provided PrintDocumentAdapter
. If a
configuration change occurs that you application does not handle, for example
a rotation change, the system will drop the connection to the adapter as the
activity has to be recreated and the old adapter may be invalid in this context,
hence a new adapter instance is required. As a consequence, if your activity
does not handle configuration changes (default behavior), you have to save the
state that you were printing and call this method again when your activity
is recreated.
printJobName
- A name for the new print job which is shown to the user.documentAdapter
- An adapter that emits the document to print.attributes
- The default print job attributes or null
.IllegalStateException
- If not called from an Activity
.IllegalArgumentException
- If the print job name is empty or the
document adapter is null.PrintJob
public List<PrintServiceInfo> getPrintServices(int selectionFlags)
PrintServicesLoader
.selectionFlags
- flags selecting which services to get. Either
ENABLED_SERVICES
,DISABLED_SERVICES
, or both.addPrintServicesChangeListener(PrintServicesChangeListener)
,
removePrintServicesChangeListener(PrintServicesChangeListener)
public List<RecommendationInfo> getPrintServiceRecommendations()
PrintServiceRecommendationsLoader
.addPrintServiceRecommendationsChangeListener(android.print.PrintManager.PrintServiceRecommendationsChangeListener)
,
removePrintServiceRecommendationsChangeListener(android.print.PrintManager.PrintServiceRecommendationsChangeListener)
public PrinterDiscoverySession createPrinterDiscoverySession()
public void setPrintServiceEnabled(ComponentName service, boolean isEnabled)
service
- The service to enabled or disableisEnabled
- whether the service should be enabled or disabled