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.
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. |