The Printer Object

The Printer object provides important and very helpful properties to print a chart. Using this object, you have control over the margins, paper orientation, color or pattern printing, among others. It is important to mention that setting these attirbutes is only benefical when generating active charts. These attributes are contained in the chart file downloaded by the client. When the chart is printed using a client side event or user action, the configured attributes are applied to the document object. Also note that the print method and printPreview method may only be accessed from the client assembly (using client side scripting).

Setting the Page Layout

When you are ready to add printing functionality to your chart, there are questions you should take into account:

  • Would you like to use the default printer margins or specify custom margins?
  • Should the printed chart use a landscape or portrait page orientation?
  • Should you prompt the user with a preview or setup dialog to make these choices themselves?

Chart FX for Java supports properties and methods that allow you to specify the exact page layout desired.

Margins

If no margins are set for a chart, the default printer margins will be used when the chart is printed. Chart FX allows you to specify the top, bottom, right and left margins using the Margins property. The margins property accepts a Rectangle object and may be configured as follows:


// Set an inch margin around the entire chart
chart1.getPrinter().setMargins(new java.awt.Rectangle(50,50,50,50));

If you would rather allow the user to configure the printing margins, you may do so by calling the pageSetup method. The pageSetup method will prompt the user with a page setup dialog box (shown in the previous section) that allows end user access to the page margins and page orientation (Landscape/Portrait). The print preview dialog may also be prompted to the user by calling the printPreview method.

Note: Methods used to print or prompt dialogs may only be called using client side scripting. The server component does not support these API members since they will have no use on the server side.

Orientation

From the page setup dialog, the end user my select to print the chart in either the landscape or portrait formats. The landscape format is longer from left to right, while the portrait format is longer from top to bottom.

You can also set the page orientation programmatically using the setOrientation property. The code below will print the chart in a landscape format:


// Set the page orientation to landscape
chart1.getPrinter().setOrientation(Orientation.LANDSCAPE);

Printing Colors

Normally if you have a black and white printer and try to print a color chart, you will receive a printout that is virtually unreadable due to the grayscales that are printed instead of the true palette colors. To resolve this issue, Chart FX includes the setForceColors method. When a color chart is printed to a B&W printer while this property is set to "false", each color in the chart is printed as a hatched pattern. This helps the end user read different series in the chart based on the contrasting patterns created in the printout. If the chart is to be printed with a color printer, you can force Chart FX to print a color chart by setting this property to "true". Below the setForceColors property is set to "true":


// Force colors to be printed
chart1.getPrinter().setForceColors(true);

Printing the Chart

Another major consideration is the number of pages that are needed to print a chart. When you have a chart with a large number of points (Scrollable) and you print that chart, Chart FX will print as many pages as necessary. The Compress property forces Chart FX to print the chart in just one page by recalculating the appropriate values so that all the points can be fixed in one page. Please note the printed chart may have a different look if you use the Compress property before printing. Below is the code used to compress and print a chart:


// Compress the chart to one printed page
chart1.getPrinter().setCompress(true);

In the code above, the print method is called to print the compressed chart. As you can see, there were no additional parameters passed with the Print method in order to print the chart. When the Print method is called with no parameters, Chart FX will print the entire chart. To print selected pages of a chart, the nFrom and nTo parameters can be passed to the chart when the method is called. This will print only the specified range of pages for the chart. If the nTo parameter is configured to zero, Chart FX will print from the specified nFrom page to the end of the chart. And if both the nFrom and nTo parameters are set to –1, only the screen shown is printed (used to print a zoomed area of a chart). Below are examples of these configurations:


// Print pages 3 thru 6
chart1.getPrinter().print(3, 6);

// Print pages 3 thru remaining pages
chart1.getPrinter().print(3, 0);

// Print the Screen (used to print a zoom area)
chart1.getPrinter().print(-1, -1);

If you would like to prompt the user with a print dialog, you may do so by calling the printDialog method. The print dialog allows the user to select the printer to be used, specify the print range and configure the number of copies to be printed. This property also uses a Boolean parameter called nFrom. When set to "true" users can modify the print range; when "false", the print range options are not available to the user. The following code will prompt the user with a print dialog:


//Prompt print dialog that allows print range modification
chart1.getPrinter().printDialog(true);

Important Note: Methods used to print or prompt dialogs may only be called using client side scripting. The server component does not support these API members since they will have no use on the server side.