This article explains how to modify the functionality of the print add-ons:
-
TLcyPrintAddOn
forILcdGXYView
maps -
TLcyLspPrintAddOn
for 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 (
ILcdGXYView
only). See Customizing the print area editor (ILcdGXYView only).
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:
-
Create all internal objects using the functions
createGXYView(id)
orcreateView(id)
, andcreateComponent(id)
, such as the overview, the header text, and so on. The created objects are stored internally and can be retrieved by calling the methodsgetGXYView(id)
/getView(id)
andgetComponent(id)
. -
Create the content of the component using
createPrintableComponentContent()
. It usesgetView(id)
/getGXYView(id)
andgetComponent(id)
to retrieve the objects created in the previous step, and lays them out in ajavax.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 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
andgetComponent
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 thecreateComponent
andgetComponent
methods end in the same suffixCOMPONENT
. 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 propertyTLcyPrintAddOn.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 propertyTLcyPrintAddOn.previewOptions.headerText
in the configuration file if you want to change the default content. By default, the filelucy/print/header.html
is used. -
FOOTER_TEXT_COMPONENT
: creates a footer text component that uses a configurable URL to provide content. Adjust the propertyTLcyPrintAddOn.previewOptions.footerText
in the configuration file if you want to change the default content. By default, the filelucy/print/footer.html
is used.
-
-
Views: the
ILcdView
instances are created in the same way as the components. Use the methodscreateGXYView
orcreateView
, andgetGXYView
orgetView
, with an ID that ends inVIEW
. These two views can be created:-
MAIN_GXYVIEW
/MAIN_VIEW
: creates a printable representation of the current map component. It is stored in the createdTLcyPrintableMapComponent
and is used to calculate the scale elements, for example. For this constant, it is not allowed to returnnull
. -
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:
-
Create all actions using
createAction(id)
, such as the print action. You can retrieve the actions afterwards usinggetAction(id)
. -
Create all components using
createComponent(id)
, the rasterization quality component for example. You can retrieve the components afterwards usinggetComponent(id)
. Because the actions are already created in the previous step, you can make use ofgetAction(id)
to create the components. -
Create all panels using
createPanel(id)
, such as the options panel. You can retrieve the panels afterwards usinggetPanel(id)
. Because the components have already been created in the previous step, you can make use ofgetComponent(id)
to create the panels. -
Create the content of the component using
createPrintPreviewContent()
. It usesgetPanel(id)
to retrieve the panels created in the previous step, lays them out in ajavax.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. -
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 genericcreateAction
andgetAction
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
andgetComponent
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 thecreateComponent
/getComponent
methods, end with the same suffixCOMPONENT
. You can use the following IDs:-
PAGE_PREVIEW_PANEL_*_COMPONENT
: several constants that represent the components of thePAGE_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
andgetPanel
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 thecreatePanel
/getPanel
methods, end with the same suffixPANEL
. 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.
Printing Example
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'.
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.