This article explains how to modify the functionality of the print add-ons:

These add-ons allow customizing the following:

Print properties

The print add-ons each have a central TLcyProperties object to communicate all kinds of print properties between the user interfaces and the actual printing functionality. Examples of those properties are the default page format, whether a title should be included, whether or not to print on scale, and so on. The object is initialized using the configuration file, lucy/print/print.cfg, so by changing the latter file you can already customize many printing properties.

For example, you can hide the footer text component of the printable component by setting the property TLcyPrintAddOn.previewOptions.footerTextSelected to false. As a result, the check box option 'footer text' in the preview dialog is de-selected, and the footer text is hidden.

For more information, refer to TLcyPrintAddOn and the configuration file itself.

Customizing the print layout

This section describes how the layout of the printed content can be modified. The printed content consists of a printable representation of the map, which is optionally decorated with a scale, legend, title, and so on. The content may be printed on a single page or on several pages.

The print add-ons represent the print layout as a java.awt.Component that is contained in a TLcyPrintableMapComponent. The content is created by a factory, meaning that it is created in small, customizable parts. For ILcdGXYView maps this factory is called TLcyPrintableComponentFactory. For Lightspeed maps, the factory is called TLcyLspPrintableMapComponentFactory. The factory has one main create function createPrintableComponent() and a number of protected methods to override the default behavior.

The main create function applies the following steps:

  1. Create all internal objects using the functions createGXYView(id) or createView(id), and createComponent(id), such as the overview, the header text, and so on. The created objects are stored internally and can be retrieved by calling the methods getGXYView(id) / getView(id) and getComponent(id).

  2. Create the content of the component using createPrintableComponentContent(). It uses getView(id) / getGXYView(id) and getComponent(id) to retrieve the objects created in the previous step, and lays them out in a javax.swing.JPanel, for example. Override this function if you want a different layout.

  3. Create the actual TLcyPrintableMapComponent, using the content created in step two.

To customize the print content layout, extend the class TLcyPrintableComponentFactory, or TLcyLspPrintableMapComponentFactory for Lightspeed maps. Then configure the print add-on to use that factory: set the configuration file property TLcyPrintAddOn.printableComponentFactory, or TLcyPrintAddOn.lightspeed.printableComponentFactory for Lightspeed maps, to the class name of the new factory, including its package name. This is demonstrated in the print sample. See Printing Example for more information about the sample.

You can use the protected methods mentioned earlier to customize the following components in the TLcyPrintableMapComponent factory:

  • Components: use a generic createComponent and getComponent method pair with an extra ID parameter. The ID describes which component it is, for example the map scale icon or the header text. All IDs that can be passed to the createComponent and getComponent methods end in the same suffix COMPONENT. The following IDs can be used:

    • LEGEND_COMPONENT: creates a tree structure of the visible layers in the current map component.

    • SCALE_ICON_COMPONENT: creates a scale icon, using the distance unit configured in Lucy.

    • SCALE_LABEL_COMPONENT: creates a scale label, using the format 'nominator : denominator'

    • TITLE_TEXT_COMPONENT: creates a title text component with configurable text as content. Adjust the property TLcyPrintAddOn.previewOptions.titleText in the configuration file if you want to change the default content.

    • HEADER_TEXT_COMPONENT: creates a header text component that uses a configurable URL to provide content. Adjust the property TLcyPrintAddOn.previewOptions.headerText in the configuration file if you want to change the default content. By default, the file lucy/print/header.html is used.

    • FOOTER_TEXT_COMPONENT: creates a footer text component that uses a configurable URL to provide content. Adjust the property TLcyPrintAddOn.previewOptions.footerText in the configuration file if you want to change the default content. By default, the file lucy/print/footer.html is used.

  • Views: the ILcdView instances are created in the same way as the components. Use the methods createGXYView or createView, and getGXYView or getView, with an ID that ends in VIEW. These two views can be created:

    • MAIN_GXYVIEW / MAIN_VIEW: creates a printable representation of the current map component. It is stored in the created TLcyPrintableMapComponent and is used to calculate the scale elements, for example. For this constant, it is not allowed to return null.

    • OVERVIEW_GXYVIEW / OVERVIEW_VIEW: creates a copy of the current map overview component.

Suppose you want to change the behavior of the footer text. The TLcyPrintableComponentFactory class shows that there is a FOOTER_TEXT_COMPONENT constant. Because it ends in COMPONENT, this constant can only be passed to the createComponent method. Therefore we can override the method createComponent, check if the ID is FOOTER_TEXT_COMPONENT and return a custom component instance. Or use super.createComponent and change some settings before returning it. If you want to remove the component completely, you can simply return null. Note that it is also possible to configure the content of the footer text, by modifying the content of the footer.html file.

Another way to finetune the printable map component is changing the configuration file. If the footer text needs to be disabled by default, for example, you can set the property TLcyPrintAddOn.previewOptions.footerTextSelected to false. This means that the footer text component will still be created, but it will remain invisible. Note that you can preview the printable map component by opening a print preview dialog box. By default, the preview dialog contains a checkbox 'footer text'. If this checkbox is selected, the footer text component will become visible, provided that it was added to the printable component. To disable the footer completely, also change the property TLcyPrintAddOn.previewOptions.footerTextVisible to false. This will remove the checkbox. Similar configuration options are available for all other options of the print preview dialog.

Customizing the print preview dialog explains how to customize the content of the print preview dialog box.

Customizing page content

Next to the printed content, which may be printed over several pages, you can also customize individual pages. You can add a title page, for example, or add a watermark to each page. The print add-ons offer the following methods to do so:

  • createPageDecorator(): allows you to specify a page decorator. This decorator is printed on top of each page. You can use it to add a watermark, for example.

  • createPrintPageable(): lets you add or remove pages before sending them to the printer. You can use it to add a title page to a printout, for example.

The print sample demonstrates how to override these methods. See Printing Example for more information.

Customizing the print preview dialog

This section describes how the content of the print preview dialog can be modified. This includes changing or replacing existing items, adding elements, or putting parts of the component, such as the options panel, in a different location.

The print add-ons provide the TLcyPrintPreviewFactory and TLcyLspPrintPreviewFactory classes to modify the print preview dialog. The creation of the content of the print preview dialog is based on the concept of a GUI factory. This means that the GUI, a java.awt.Component in this case, is created in small, customizable parts. The print preview dialog factory has one main create function createPrintPreview() and a number of protected methods to override the default behavior. The main create function will apply the following steps:

  1. Create all actions using createAction(id), such as the print action. You can retrieve the actions afterwards using getAction(id).

  2. Create all components using createComponent(id), the rasterization quality component for example. You can retrieve the components afterwards using getComponent(id). Because the actions are already created in the previous step, you can make use of getAction(id) to create the components.

  3. Create all panels using createPanel(id), such as the options panel. You can retrieve the panels afterwards using getPanel(id). Because the components have already been created in the previous step, you can make use of getComponent(id) to create the panels.

  4. Create the content of the component using createPrintPreviewContent(). It uses getPanel(id) to retrieve the panels created in the previous step, lays them out in a javax.swing.JPanel for example, and adds the titles. Override this function if you want to rearrange the layout of those panels, or add a custom panel.

  5. Create the actual java.awt.Component, using the content created in the previous step.

When you are customizing the page layout, extend the class TLcyPrintPreviewFactory, or TLcyLspPrintPreviewFactory for Lightspeed maps, and configure the print add-on to use that factory: set the configuration file property TLcyPrintAddOn.printPreviewFactory, or TLcyPrintAddOn.lightspeed.printPreviewFactory for Lightspeed maps, to the class name of the new factory, including its package name.

You can use the protected methods mentioned earlier to customize the following components:

  • Actions: the ILcdAction objects are manipulated through a generic createAction and getAction method pair with an extra ID parameter. The ID describes which action it is. Currently only one action ID is available: PRINT_ACTION. By default, it just prints out the current printable component.

  • Components: use a generic createComponent and getComponent method pair with an extra ID parameter. The ID describes which component it is, the options or the preview area settings panel for example. All IDs that can be passed to the createComponent / getComponent methods, end with the same suffix COMPONENT. You can use the following IDs:

    • PAGE_PREVIEW_PANEL_*_COMPONENT: several constants that represent the components of the PAGE_PREVIEW_PANEL, such as the scroll pane that contains the preview of the actual pages. See the API reference documentation for more details.

    • OPTIONS_PANEL_*_COMPONENT: several constants that represent the components of the options panel, such as the quality slider, or the header text checkbox. See the API reference documentation for more details.

  • Panels: panels are manipulated through a generic createPanel and getPanel method pair with an extra ID parameter. The ID describes which panel it is, the options or the preview area settings panel for example. All IDs that can be passed to the createPanel / getPanel methods, end with the same suffix PANEL. You can use the following IDs:

    • PRINTER_SETTINGS_PANEL: creates a component that allows the user to change some of the printer and the page format settings.

    • PRINTING_AREA_PANEL: creates a settings panel corresponding to the printing area.

    • OPTIONS_PANEL: creates the options panel. The user can use this panel to change printing options such as the visibility of the footer text in the printable component.

    • PAGE_PREVIEW_PANEL: creates a panel with a combo box to adjust the preview scale.

    • PRINT_PANEL: creates a panel with a print and close action.

Suppose that you want to change the behavior of the options panel. The TLcyPrintPreviewFactory class shows that there is an OPTIONS_PANEL constant. Because it ends in PANEL, this constant can only be passed to the createPanel method. Therefore, we can override the method createPanel, check if the ID is OPTIONS_PANEL and return a custom component instance. Alternatively, you can use super.createPanel and change some settings before returning it. If you want to remove the component completely, you can simply return null.

You can also finetune the content of the print preview dialog by changing the configuration file. If the user is not allowed to change the visibility of the footer text, for example, the property TLcyPrintAddOn.previewOptions.footerTextVisible can be set to false. This means that the corresponding checkbox will not be added to the options panel. Note that this does not mean that the footer text in the TLcyPrintableMapComponent is hidden. As mentioned in Customizing the print layout, the property TLcyPrintAddOn.previewOptions.footerTextSelected handles the visibility of that component.

Customizing the print area editor (ILcdGXYView only)

You can use the Define Print Area action in the File menu to draw the area to print on an ILcdGXYView-based map. When that print area object is selected, an editor is displayed by the TLcySelectionEditorAddOn.

The displayed editor is created by the TLcyPrintAreaCustomizerFactory. Whenever you want to customize that editor, the same principle applies: write an extension of TLcyPrintAreaCustomizerFactory. Then, configure the TLcyPrintAddOn to use that factory, by adapting the TLcyPrintAddOn.printAreaCustomizerFactory configuration property. The extension can override createPrintAreaCustomizerPanelContent to change the layout, for example, or override createPanel to replace a single part.

The print sample implements several customizations. The main class is samples.lucy.printing.Main.

One customization to pay particular attention to is the custom printable map component. The add-ons file of this sample, addons_print_sample.xml, shows that the print add-ons are configured with custom configuration files. The files specify a custom ALcyPrintableMapComponentFactory that changes the layout of the content of the printable component. The legend, scale icon and scale indication components are located on the right side of the map. The overview is no longer in the bottom right corner, but in the top right corner.

To change the layout of the printable component, you have to override the method createPrintableComponentContent(). You can retrieve the components as demonstrated in Program: This snippet shows how to retrieve the individual parts of the page. The ID is used to decide which object needs to be returned. You can modify the layout of the java.awt.Component as required, by adding them to a javax.swing.JPanel with a layout manager of your choice. Because the new layout in the sample looks better in landscape mode, the corresponding configuration setting in the configuration file was set to 'LANDSCAPE'.

Program: This snippet shows how to retrieve the individual parts of the page (from samples/lucy/printing/PrintableMapComponentFactory) 
Component titleText = getComponent(TITLE_TEXT_COMPONENT);
Component headerText = getComponent(MODIFIABLE_HEADER_TEXT_COMPONENT);
Component classification = getComponent(CLASSIFICATION_COMPONENT);
Component legend = getComponent(LEGEND_COMPONENT);
Component scaleLabel = getComponent(SCALE_LABEL_COMPONENT);
Component scaleIcon = getComponent(SCALE_ICON_COMPONENT);
Component overview = (Component) getGXYView(OVERVIEW_GXYVIEW);
Component view = (Component) getGXYView(MAIN_GXYVIEW);

Note that we do not need the footer text component in our custom layout, but when the default preview dialog opens, the checkbox 'footer text' is still shown. This checkbox is useless, so it could be removed from the panel. Instead of extending the TLcyPrintPreviewFactory, you can set the configuration file property TLcyPrintAddOn.previewOptions.footerTextVisible to false. This makes sure the checkbox will not be added to the options panel. Because the footer text component was not used in our custom layout, nothing happens if the value of the property TLcyPrintAddOn.previewOptions.footerTextSelected changes.