* It includes *
* Here ia a very simple example, which prints a single node. *
* Node node = new Circle(100, 200, 200);
* PrinterJob job = PrinterJob.createPrinterJob();
* if (job != null) {
* boolean success = job.printPage(node);
* if (success) {
* job.endJob();
* }
* }
*
* Points to note
* * In the example above the node was not added to a scene. * Since most printing scenarios are printing content that's either * not displayed at all, or must be prepared and formatted differently, * this is perfectly acceptable. *
* If content that is currently part of a Scene and is being displayed, * is printed, then because printing a job or even a single page * of the job may span over multiple screen "pulses" or frames, it is * important for the application to ensure that the node being printed * is not updated during the printing process, else partial or smeared * rendering is probable. *
* It should be apparent that the same applies even to nodes that are * not displayed - updating them concurrent with printing them is not * a good idea. *
* There is no requirement to do printing on the FX application thread. * A node may be prepared for printing on any thread, the job may * be invoked on any thread. However, minimising the amount of work * done on the FX application thread is generally desirable, * so as not to affect the responsiveness of the application UI. * So the recommendation is to perform printing on a new thread * and let the implementation internally schedule any tasks that * need to be performed on the FX thread to be run on that thread. *
* @since JavaFX 8.0
*/
public final class PrinterJob {
// Delegating all the work keeps whatever classes
// are being used out of the API packages.
private PrinterJobImpl jobImpl;
private ObjectProperty
* The
* The above applies whether the printer is changed by directly calling
* this method, or as a side-effect of user interaction with a print
* dialog.
*
* Setting a null value for printer will install the default printer.
* Setting the current printer has no effect.
* @param printer to be used for this print job.
*/
public synchronized void setPrinter(Printer printer) {
printerProperty().set(printer);
}
/**
* The
* In the case that there is no UI available then this method
* returns true, with no options changed, as if the user had
* confirmed to proceed with printing.
*
* If the job is not in a state to display the dialog, such
* as already printing, cancelled or done, then the dialog will
* not be displayed and the method will return false.
*
* The window
* This will display the most appropriate available dialog for
* this purpose.
* However there may be still be access to other settings,
* including changing the current printer.
* Therefore a side effect of this dialog display method may be to
* update that and any other current job settings.
* The method returns true if the user confirmed the dialog whether or
* not any changes are made.
*
* If the job is not in a state to display the dialog, such
* as already printing, cancelled or done, then the dialog will
* not be displayed and the method will return false.
*
* The window
* This method does not update the job configuration.
* @param pageLayout to be validated
* @return a
* The typical life cycle of a job is as follows :
*
* A job may not revert to an earlier status in its life cycle and
* the current job state affects operations that may be performed.
* For example a job may not begin printing again if it has previously
* passed that state and entered any of the termination states.
*
* @since JavaFX 8.0
*/
public static enum JobStatus {
/**
* The new job status. May display print dialogs and
* configure the job and initiate printing.
*/
NOT_STARTED,
/**
* The job has requested to print at least one page,
* and has not terminated printing. May no longer
* display print dialogs.
*/
PRINTING,
/**
* The job has been cancelled by the application.
* May not display dialogs or initiate printing.
* Job should be discarded. There is no need to
* call endJob().
*/
CANCELED,
/**
* The job encountered an error.
* Job should be discarded. There is no need to
* call endJob().
*/
ERROR,
/**
* The job initiated printing and later called endJob()
* which reported success. The job can be discarded
* as it cannot be re-used.
*/
DONE
};
private ReadOnlyObjectWrapper
* The call has no effect if the job has already been requested
* to be CANCELED, or is in the state ERROR or DONE.
* For example it will not de-queue from the printer a job that
* has already been spooled for printing.
* Once a job is cancelled, it is not valid to call any methods
* which render new content or change job state.
*/
public void cancelJob() {
if (jobStatus.get().ordinal() <= JobStatus.PRINTING.ordinal()) {
jobStatus.set(JobStatus.CANCELED);
jobImpl.cancelJob();
}
}
/**
* If the job can be successfully spooled to the printer queue
* this will return true. Note : this does not mean the job already
* printed as that could entail waiting for minutes or longer,
* even where implementable.
*
* A return value of false means the job could not be spooled,
* or was already completed.
*
* Successful completion will also update job status to
* Calling endJob() on a job for which no pages have been printed
* is equivalent to calling {code cancelJob()}.
* @return true if job is spooled, false if its not, or the job
* was already in a completed state.
*/
public synchronized boolean endJob() {
if (jobStatus.get() == JobStatus.NOT_STARTED) {
cancelJob();
return false;
} else if (jobStatus.get() == JobStatus.PRINTING) {
boolean rv = jobImpl.endJob();
jobStatus.set(rv ? JobStatus.DONE : JobStatus.ERROR);
return rv;
} else {
return false;
}
}
@Override
public String toString() {
return "JavaFX PrinterJob " +
getPrinter() + "\n" +
getJobSettings() + "\n" +
"Job Status = " + getJobStatus();
}
}
printer argument determines the initial printer
* @param printer to use for the job. If the printer is currently
* unavailable (eg offline) then this may return null.
* @return a new PrinterJob, or null.
* @throws SecurityException if a job does not have permission
* to initiate a printer job.
*/
public static final PrinterJob createPrinterJob(Printer printer) {
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkPrintJobAccess();
}
return new PrinterJob(printer);
}
private PrinterJob(Printer printer) {
this.printer = createPrinterProperty(printer);
settings = printer.getDefaultJobSettings();
settings.setPrinterJob(this);
createImplJob(printer, settings);
}
synchronized private PrinterJobImpl createImplJob(Printer printer,
JobSettings settings) {
if (jobImpl == null) {
jobImpl = PrintPipeline.getPrintPipeline().createPrinterJob(this);
}
return jobImpl;
}
/**
* Updating settings or printer is only allowed on a new job,
* meaning before you start printing or cancel etc.
* The implementation needs to check this wherever job state
* updates are received.
*/
boolean isJobNew() {
return getJobStatus() == JobStatus.NOT_STARTED;
}
private ObjectPropertyPrinter for this job.
*/
public final ObjectPropertyJobSettings encapsulates all the API supported job
* configuration options such as number of copies,
* collation option, duplex option, etc.
* The initial values are based on the current settings for
* the initial printer.
* @return current job settings.
*/
public synchronized JobSettings getJobSettings() {
return settings;
}
/**
* Displays a Print Dialog.
* Allow the user to update job state such as printer and settings.
* These changes will be available in the appropriate properties
* after the print dialog has returned.
* The print dialog is also typically used to confirm the user
* wants to proceed with printing. This is not binding on the
* application but generally should be obeyed.
* owner may be null, but
* if it is a visible Window, it will be used as the parent.
* @param owner to which to block input, or null.
* @return false if the user opts to cancel printing, or the job
* is not in the new state. That is if it has already started,
* has failed, or has been cancelled, or ended.
* @throws IllegalStateException if this is called on the FX application
* thread, outside of an event handler. This includes animation callbacks,
* properties handlers and layout processing.
*/
public synchronized boolean showPrintDialog(Window owner) {
// TBD handle owner
if (!isJobNew()) {
return false;
} else {
return jobImpl.showPrintDialog(owner);
}
}
/**
* Displays a Page Setup dialog.
* A page set up dialog is primarily to allow an end user
* to configure the layout of a page. Paper size and orientation
* are the most common and most important components of this.
* owner may be null, but
* if it is a visible Window, it will be used as the parent.
* @param owner to block input, or null.
* @return false if the user opts to cancel the dialog, or the job
* is not in the new state. That is if it has already started,
* has failed, or has been cancelled, or ended.
* @throws IllegalStateException if this is called on the FX application
* thread, outside of an event handler. This includes animation callbacks,
* properties handlers and layout processing.
*/
public synchronized boolean showPageSetupDialog(Window owner) {
// TBD handle owner
if (!isJobNew()) {
return false;
} else {
return jobImpl.showPageDialog(owner);
}
}
/**
* This method can be used to check if a page configuration
* is possible in the current job configuration. For example
* if the specified paper size is supported. If the original
* PageLayout is supported it will be returned. If not, a new PageLayout
* will be returned that attempts to honour the supplied
* PageLayout, but adjusted to match the current job configuration.
* PageLayout that is supported in the
* current job configuration.
* @throws NullPointerException if the pageLayout parameter is null.
*/
synchronized PageLayout validatePageLayout(PageLayout pageLayout) {
if (pageLayout == null) {
throw new NullPointerException("pageLayout cannot be null");
}
return jobImpl.validatePageLayout(pageLayout);
}
/**
* Print the specified node using the specified page layout.
* The page layout will override the job default for this page only.
* If the job state is CANCELED, ERROR or DONE, this method will
* return false.
* @param pageLayout Layout for this page.
* @param node The node to print.
* @return whether rendering was successful.
* @throws NullPointerException if either parameter is null.
* @throws IllegalStateException if this is called on the FX application
* thread, outside of an event handler. This includes animation callbacks,
* properties handlers and layout processing.
*/
public synchronized boolean printPage(PageLayout pageLayout, Node node) {
if (jobStatus.get().ordinal() > JobStatus.PRINTING.ordinal()) {
return false;
}
if (jobStatus.get() == JobStatus.NOT_STARTED) {
jobStatus.set(JobStatus.PRINTING);
}
if (pageLayout == null || node == null) {
jobStatus.set(JobStatus.ERROR);
throw new NullPointerException("Parameters cannot be null");
}
boolean rv = jobImpl.print(pageLayout, node);
if (!rv) {
jobStatus.set(JobStatus.ERROR);
}
return rv;
}
/**
* Print the specified node. The page layout is the job default.
* If the job state is CANCELED, ERROR or DONE, this method will
* return false.
* @param node The node to print.
* @return whether rendering was successful.
* @throws NullPointerException if the node parameter is null.
*/
public synchronized boolean printPage(Node node) {
return printPage(settings.getPageLayout(), node);
}
/**
* An enum class used in reporting status of a print job.
* Applications can listen to the job status via the
* {@link #jobStatus jobStatus} property, or may query it directly
* using {@link javafx.print.PrinterJob#getJobStatus getJobStatus()}.
*
*
* NOT_STARTED and
* will stay there during configuration via dialogs etc.
* PRINTING when the first page
* is printed.
* DONE once the job is
* successfully completed without being cancelled or encountering
* an error. The job is now completed.
* ERROR or is
* CANCELED is also considered completed.
* JobStatus
*/
public ReadOnlyObjectPropertyJobStatus
*/
public JobStatus getJobStatus() {
return jobStatus.get();
}
/**
* Cancel the underlying print job at the earliest opportunity.
* It may return immediately without waiting for the job cancellation
* to be complete in case this would block the FX user thread
* for any period of time.
* If printing is in process at that time, then typically
* this means cancellation is after the current page is rendered.
* The job status is updated to CANCELED only once that has happened.
* Thus determining that the job is CANCELED requires monitoring
* the job status.
* DONE,
* at which point the job can no longer be used.
*