java.lang.Object | |
↳ | android.print.PrintManager |
System level service for accessing the printing capabilities of the platform.
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.
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Gets the print jobs for this application.
| |||||||||||
Creates a print job for printing a
PrintDocumentAdapter with
default print attributes. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Creates a print job for printing a 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. |