FileDocCategorySizeDatePackage
PrintManager.javaAPI DocAndroid 5.1 API40585Thu Mar 12 22:22:10 GMT 2015android.print

PrintManager

public final class PrintManager extends Object
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);

Print mechanics

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 {@link 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

Print jobs are started by calling the {@link #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 {@link PrintJobInfo#STATE_CREATED created}, {@link PrintJobInfo#STATE_QUEUED queued}, {@link PrintJobInfo#STATE_STARTED started}, {@link PrintJobInfo#STATE_BLOCKED blocked}, {@link PrintJobInfo#STATE_COMPLETED completed}, {@link PrintJobInfo#STATE_FAILED failed}, and {@link PrintJobInfo#STATE_CANCELED 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.

see
PrintJob
see
PrintJobInfo

Fields Summary
private static final String
LOG_TAG
private static final boolean
DEBUG
private static final int
MSG_NOTIFY_PRINT_JOB_STATE_CHANGED
public static final String
ACTION_PRINT_DIALOG
The action for launching the print dialog activity.
public static final String
EXTRA_PRINT_DIALOG_INTENT
Extra with the intent for starting the print dialog.

Type: {@link android.content.IntentSender}

public static final String
EXTRA_PRINT_JOB
Extra with a print job.

Type: {@link android.print.PrintJobInfo}

public static final String
EXTRA_PRINT_DOCUMENT_ADAPTER
Extra with the print document adapter to be printed.

Type: {@link android.print.IPrintDocumentAdapter}

public static final int
APP_ID_ANY
private final android.content.Context
mContext
private final IPrintManager
mService
private final int
mUserId
private final int
mAppId
private final android.os.Handler
mHandler
private Map
mPrintJobStateChangeListeners
Constructors Summary
public PrintManager(android.content.Context context, IPrintManager service, int userId, int appId)
Creates a new instance.

param
context The current context in which to operate.
param
service The backing system service.
hide


      
       

                               
           
    

                             
             
        mContext = context;
        mService = service;
        mUserId = userId;
        mAppId = appId;
        mHandler = new Handler(context.getMainLooper(), null, false) {
            @Override
            public void handleMessage(Message message) {
                switch (message.what) {
                    case MSG_NOTIFY_PRINT_JOB_STATE_CHANGED: {
                        SomeArgs args = (SomeArgs) message.obj;
                        PrintJobStateChangeListenerWrapper wrapper =
                                (PrintJobStateChangeListenerWrapper) args.arg1;
                        PrintJobStateChangeListener listener = wrapper.getListener();
                        if (listener != null) {
                            PrintJobId printJobId = (PrintJobId) args.arg2;
                            listener.onPrintJobStateChanged(printJobId);
                        }
                        args.recycle();
                    } break;
                }
            }
        };
Methods Summary
public voidaddPrintJobStateChangeListener(android.print.PrintManager$PrintJobStateChangeListener listener)
Adds a listener for observing the state of print jobs.

param
listener The listener to add.
hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return;
        }
        if (mPrintJobStateChangeListeners == null) {
            mPrintJobStateChangeListeners = new ArrayMap<PrintJobStateChangeListener,
                    PrintJobStateChangeListenerWrapper>();
        }
        PrintJobStateChangeListenerWrapper wrappedListener =
                new PrintJobStateChangeListenerWrapper(listener, mHandler);
        try {
            mService.addPrintJobStateChangeListener(wrappedListener, mAppId, mUserId);
            mPrintJobStateChangeListeners.put(listener, wrappedListener);
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error adding print job state change listener", re);
        }
voidcancelPrintJob(PrintJobId printJobId)

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return;
        }
        try {
            mService.cancelPrintJob(printJobId, mAppId, mUserId);
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error canceling a print job: " + printJobId, re);
        }
public PrinterDiscoverySessioncreatePrinterDiscoverySession()

hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return null;
        }
        return new PrinterDiscoverySession(mService, mContext, mUserId);
public java.util.ListgetEnabledPrintServices()
Gets the list of enabled print services.

return
The enabled service list or an empty list.
hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return Collections.emptyList();
        }
        try {
            List<PrintServiceInfo> enabledServices = mService.getEnabledPrintServices(mUserId);
            if (enabledServices != null) {
                return enabledServices;
            }
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error getting the enabled print services", re);
        }
        return Collections.emptyList();
public android.print.PrintManagergetGlobalPrintManagerForUser(int userId)
Creates an instance that can access all print jobs.

param
userId The user id for which to get all print jobs.
return
An instance if the caller has the permission to access all print jobs, null otherwise.
hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return null;
        }
        return new PrintManager(mContext, mService, userId, APP_ID_ANY);
public java.util.ListgetInstalledPrintServices()
Gets the list of installed print services.

return
The installed service list or an empty list.
hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return Collections.emptyList();
        }
        try {
            List<PrintServiceInfo> installedServices = mService.getInstalledPrintServices(mUserId);
            if (installedServices != null) {
                return installedServices;
            }
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error getting the installed print services", re);
        }
        return Collections.emptyList();
public PrintJobgetPrintJob(PrintJobId printJobId)
Gets a print job given its id.

return
The print job list.
see
PrintJob
hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return null;
        }
        try {
            PrintJobInfo printJob = mService.getPrintJobInfo(printJobId, mAppId, mUserId);
            if (printJob != null) {
                return new PrintJob(printJob, this);
            }
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error getting print job", re);
        }
        return null;
PrintJobInfogetPrintJobInfo(PrintJobId printJobId)

        try {
            return mService.getPrintJobInfo(printJobId, mAppId, mUserId);
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error getting a print job info:" + printJobId, re);
        }
        return null;
public java.util.ListgetPrintJobs()
Gets the print jobs for this application.

return
The print job list.
see
PrintJob

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return Collections.emptyList();
        }
        try {
            List<PrintJobInfo> printJobInfos = mService.getPrintJobInfos(mAppId, mUserId);
            if (printJobInfos == null) {
                return Collections.emptyList();
            }
            final int printJobCount = printJobInfos.size();
            List<PrintJob> printJobs = new ArrayList<PrintJob>(printJobCount);
            for (int i = 0; i < printJobCount; i++) {
                printJobs.add(new PrintJob(printJobInfos.get(i), this));
            }
            return printJobs;
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error getting print jobs", re);
        }
        return Collections.emptyList();
public PrintJobprint(java.lang.String printJobName, PrintDocumentAdapter documentAdapter, PrintAttributes attributes)
Creates a print job for printing a {@link PrintDocumentAdapter} with default print attributes.

Calling this method brings the print UI allowing the user to customize the print job and returns a {@link PrintJob} object without waiting for the user to customize or confirm the print job. The returned print job instance is in a {@link PrintJobInfo#STATE_CREATED created} state.

This method can be called only from an {@link 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 {@link 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 {@link 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.

param
printJobName A name for the new print job which is shown to the user.
param
documentAdapter An adapter that emits the document to print.
param
attributes The default print job attributes or null.
return
The created print job on success or null on failure.
throws
IllegalStateException If not called from an {@link Activity}.
throws
IllegalArgumentException If the print job name is empty or the document adapter is null.
see
PrintJob

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return null;
        }
        if (!(mContext instanceof Activity)) {
            throw new IllegalStateException("Can print only from an activity");
        }
        if (TextUtils.isEmpty(printJobName)) {
            throw new IllegalArgumentException("printJobName cannot be empty");
        }
        if (documentAdapter == null) {
            throw new IllegalArgumentException("documentAdapter cannot be null");
        }
        PrintDocumentAdapterDelegate delegate = new PrintDocumentAdapterDelegate(
                (Activity) mContext, documentAdapter);
        try {
            Bundle result = mService.print(printJobName, delegate,
                    attributes, mContext.getPackageName(), mAppId, mUserId);
            if (result != null) {
                PrintJobInfo printJob = result.getParcelable(EXTRA_PRINT_JOB);
                IntentSender intent = result.getParcelable(EXTRA_PRINT_DIALOG_INTENT);
                if (printJob == null || intent == null) {
                    return null;
                }
                try {
                    mContext.startIntentSender(intent, null, 0, 0, 0);
                    return new PrintJob(printJob, this);
                } catch (SendIntentException sie) {
                    Log.e(LOG_TAG, "Couldn't start print job config activity.", sie);
                }
            }
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error creating a print job", re);
        }
        return null;
public voidremovePrintJobStateChangeListener(android.print.PrintManager$PrintJobStateChangeListener listener)
Removes a listener for observing the state of print jobs.

param
listener The listener to remove.
hide

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return;
        }
        if (mPrintJobStateChangeListeners == null) {
            return;
        }
        PrintJobStateChangeListenerWrapper wrappedListener =
                mPrintJobStateChangeListeners.remove(listener);
        if (wrappedListener == null) {
            return;
        }
        if (mPrintJobStateChangeListeners.isEmpty()) {
            mPrintJobStateChangeListeners = null;
        }
        wrappedListener.destroy();
        try {
            mService.removePrintJobStateChangeListener(wrappedListener, mUserId);
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error removing print job state change listener", re);
        }
voidrestartPrintJob(PrintJobId printJobId)

        if (mService == null) {
            Log.w(LOG_TAG, "Feature android.software.print not available");
            return;
        }
        try {
            mService.restartPrintJob(printJobId, mAppId, mUserId);
        } catch (RemoteException re) {
            Log.e(LOG_TAG, "Error restarting a print job: " + printJobId, re);
        }