This article explains how to modify the functionality of the print add-ons:
TLcyLspPrintAddOnfor Lightspeed maps
These add-ons allow customizing the following:
Various printing configuration properties. See Print properties.
The layout and content of what gets printed. See Customizing the print layout and Customizing page content.
The layout and content of the print preview dialog. See Customizing the print preview dialog.
The layout and content of the print area editor (
ILcdGXYViewonly). See Customizing the print area editor (ILcdGXYView only).
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
The content is created by a factory, meaning that it is created in small, customizable parts.
ILcdGXYView maps this factory is called
TLcyPrintableComponentFactory. For Lightspeed maps, the factory is called
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:
Create all internal objects using the functions
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
Create the content of the component using
createPrintableComponentContent(). It uses
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.
Create the actual
TLcyPrintableMapComponent, using the content created in step two.
To customize the print content layout, extend the class
TLcyLspPrintableMapComponentFactory for Lightspeed maps. Then configure the print add-on to use that factory: set the configuration file property
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
Components: use a generic
getComponentmethod 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
getComponentmethods 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.titleTextin 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.headerTextin the configuration file if you want to change the default content. By default, the file
FOOTER_TEXT_COMPONENT: creates a footer text component that uses a configurable URL to provide content. Adjust the property
TLcyPrintAddOn.previewOptions.footerTextin the configuration file if you want to change the default content. By default, the file
ILcdViewinstances are created in the same way as the components. Use the methods
getView, with an ID that ends in
VIEW. These two views can be created:
MAIN_VIEW: creates a printable representation of the current map component. It is stored in the created
TLcyPrintableMapComponentand is used to calculate the scale elements, for example. For this constant, it is not allowed to return
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
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
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
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:
Create all actions using
createAction(id), such as the print action. You can retrieve the actions afterwards using
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.
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.
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.JPanelfor example, and adds the titles. Override this function if you want to rearrange the layout of those panels, or add a custom panel.
Create the actual
java.awt.Component, using the content created in the previous step.
When you are customizing the page layout, extend the class
TLcyLspPrintPreviewFactory for Lightspeed maps, and configure the print add-on to use that factory: set the configuration file property
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:
ILcdActionobjects are manipulated through a generic
getActionmethod 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
getComponentmethod 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
getComponentmethods, 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
getPanelmethod 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
getPanelmethods, 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
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
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
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'.
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