<html xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://jasperreports.sourceforge.net/jasperreports">
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>JasperReports 4.0.2 - Fonts Sample</title>
<style type="text/css">
.title {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 28px;
font-weight: normal;
}
.toc {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.name {
font-family: Courier New, Courier, serif;
font-size: 16px;
font-weight: bold;
}
.label {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: bold;
font-style: italic;
}
.description {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: normal;
}
.value {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.element {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.attribute {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: bold;
}
.code {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.copy {
font-decoration: none;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 8pt;
font-style: normal;
color: #000000;
}
.subtitle {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: bold;
text-decoration: none;
color: inherit;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td colspan="2" align="right"><span class="element"><a href="../../sample.reference.html">Sample Reference</a> - <a href="../../schema.reference.html">Schema Reference</a> - <a href="../../config.reference.html">Configuration Reference</a> - <a href="http://jasperreports.sourceforge.net/api/index.html">API (Javadoc)</a></span>
<br>
</td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
<tr valign="middle">
<td nowrap="true"><span class="title">JasperReports - Fonts Sample (version 4.0.2)</span></td><td align="right"><img src="../../resources/jasperreports.png" border="0"></td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
</table>
<br>
<span class="description"><span class="description">Shows how to work with fonts.</span></span>
<br>
<br>
<span class="element"><a href="http://sourceforge.net/projects/jasperreports/files/jasperreports/JasperReports%204.0.2/jasperreports-4.0.2-project.zip/download" target="_blank">Download All Sample Source Files</a></span>
<br>
<span class="element"><a href="http://jasperforge.org/scm/viewvc.php/tags/jr-4-0-2/jasperreports/demo/samples/fonts/?root=jasperreports" target="_blank">Browse Sample Source Files on SVN</a></span>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td style="width: 20px;">
<br>
</td><td>
<br>
</td>
</tr>
<tr>
<td colspan="2"><span class="label">Main Features in This Sample</span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#fonts">Fonts</a></span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#fontextensions">Font Extensions</a></span></td>
</tr>
</table>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td width="80%">
<br>
</td><td width="20%">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="fonts"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Fonts</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.org" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to format texts using fonts properties.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">0.1.0</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<b>Characters and Fonts</b>
<br>
<br>
Any text is represented by a character sequence with particular formatting settings.
Some of these appearance settings can be specified using the <span class="code"><code><font/></code></span> tag available in
the <span class="code"><code><textElement/></code></span> tag. If there are shared font settings among several text elements,
we strongly encourage people to group them in report styles defined in style templates (see the
<a href="../templates/index.html" target="_blank" class="element">Templates</a> sample).
<br>
<br>
<b>Note:</b> Report fonts are now deprecated. Do not use <span class="code"><code><reportFont/></code></span> elements declared
within the document itself. Such font declarations may have impact on generated document performance.
<br>
<br>
The main font settings available in JasperReports are:
<ul>
<li>
<span class="code"><code>fontName</code></span> - the font name, which can be the name of a physical font or a logical one.</li>
<li>
<span class="code"><code>size</code></span> - the size of the font measured in points. It defaults to 10.</li>
<li>
<span class="code"><code>isBold</code></span> - flag specifying if a <b>bold</b> font is required. It defaults to <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>isItalic</code></span> - flag specifying if an <i>italic</i> font is required. It defaults to <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>isUnderline</code></span> - flag specifying if the <u>underline</u> text decoration is required. It defaults to <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>isStrikeThrough</code></span> - flag specifying if the <del>strikethrough</del> text decoration is required. It defaults to <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>pdfFontName</code></span> - the name of an equivalent PDF font required by the iText library when exporting documents to PDF format.</li>
<li>
<span class="code"><code>pdfEncoding</code></span> - the equivalent PDF character encoding, also required by the iText library.</li>
<li>
<span class="code"><code>isPdfEmbedded</code></span> - flag that specifies whether the font should be embedded into the document itself. It defaults to <span class="code"><code>false</code></span>.</li>
</ul>
<b>Character Encoding</b>
<br>
<br>
Another important feature to consider when working with texts, especially if they are intended to be internationalized,
is the character encoding. That's because different charsets
provide their own character representation for the same character code.
<br>
The default document encoding value is <span class="code"><code>UTF-8</code></span>.
<br>
For more information about how to set the character encoding, please consult the <a href="../unicode/index.html" target="_blank" class="element">Unicode</a> sample.
<br>
<br>
<b>Default Fonts and Inheritance</b>
<br>
<br>
Another interesting feature is that each text element inherits font and style attributes from its parent element. And each parent
element inherits these attributes from its parent, etc. If no styles and/or fonts are defined for elements, the default style (and/or
font - but this is now deprecated) declared in the <span class="code"><code><jasperReport/></code></span> root element will be applied.
<br>
A default style is characterized by the <span class="code"><code>isDefault</code></span> flag attribute:
<pre>
<style name="Base" isDefault="true" hAlign="Center" vAlign="Middle"
fontSize="10" pdfFontName="Helvetica" pdfEncoding="Cp1252" isPdfEmbedded="false">
<box padding="4">
<pen lineWidth="0.5"/>
</box>
</style></pre>
However, defining default styles or fonts in JasperReports is not mandatory. If no font is defined for a given element, the engine looks either
for the inherited font attributes, or, if no attributes are found on this way, it looks for the
<br>
<br>
<span class="code"><code>net.sf.jasperreports.default.font.name</code></span>
<br>
<br>
property in the <span class="code"><code>/src/default.jasperreports.properties</code></span> file. Its value defines the name of the font family to be used
when font properties are not explicitly defined for a text element or inherited from its parent.
<br>
<br>
The main default font properties and their values defined in the <span class="code"><code>/src/default.jasperreports.properties</code></span> file are:
<ul>
<li>
<span class="code"><code>net.sf.jasperreports.default.font.name=SansSerif</code></span> - the default font name.</li>
<li>
<span class="code"><code>net.sf.jasperreports.default.font.size=10</code></span> - the default font size.</li>
<li>
<span class="code"><code>net.sf.jasperreports.default.pdf.font.name=Helvetica</code></span> - the default PDF font.</li>
<li>
<span class="code"><code>net.sf.jasperreports.default.pdf.encoding=Cp1252</code></span> - the default PDF character encoding.</li>
<li>
<span class="code"><code>net.sf.jasperreports.default.pdf.embedded=false</code></span> - by default PDF fonts are not embedded</li>
</ul>
The bold, italic, and all text decorations properties are missing, which means that default fonts are not bold, not oblique and not decorated.
<br>
<br>
<b>The Fonts Sample</b>
<br>
<br>
This sample shows some practical examples of using fonts and font attributes in order to get a particular text appearance.
<br>
Because this sample uses a font extension based on the Gentium open source font files, and logical JVM font names also, it is strongly
recommended to consult first the <a href="#fontextensions" target="_blank" class="element">Font Extensions</a> section below, and then to compile and run the sample.
<br>
<br>
In the example below, a series of font attributes are defined for the static text element:
<pre>
<staticText>
<reportElement x="0" y="350" width="150" height="40"/>
<textElement>
<font fontName="Monospaced" size="12" isItalic="true" isUnderline="true" pdfFontName="Courier-Oblique"/>
</textElement>
<text>The quick brown fox jumps over the lazy dog.</text>
</staticText></pre>
One can say that this text will use a monospaced character set, 12 pts sized, underlined and oblique, and when exporting to
PDF format, the equivalent fonts will be Courier-Oblique.
<br>
<br>
<b>Running the Sample</b>
<br>
<br>
Running the sample requires the <a href="http://ant.apache.org/" target="_blank" class="element">Apache Ant</a> library. Make sure that <span class="code"><code>ant</code></span> is already installed on your system (version 1.5 or later).
<br>
In a command prompt/terminal window set the current folder to <span class="code"><code>demo/samples/fonts</code></span> within the JasperReports source project and run the <span class="code"><code>> ant test view</code></span> command.
<br>
It will generate all supported document types containing the sample report in the <span class="code"><code>demo/samples/fonts/build/reports</code></span> directory.
A font extension sample xml file named <span class="code"><code>fonts.xml</code></span> will be also generated in the same directory. It contains all font families
available in the already installed font extensions.
<br>
Then the report will open in the JasperReports internal viewer.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="fontextensions"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Font Extensions</span></td><td align="right"><span class="copy">Documented by
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to ship the required fonts with your report templates when deploying them in the target application, using font extensions.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">3.1.3</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Other Samples</span></td><td>
<br>
</td><td colspan="3">
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><span class="element"><a href="../unicode/index.html">/demo/samples/unicode</a></span></td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<b>About Fonts Extension</b>
<br>
<br>
Formerly used font definitions relied on font files available on the machine.
In this case, when defining how a piece of text should look like, one had to take care about the following possible issues:
<ul>
<li>The needed font library might not be available to the JVM at runtime
because the font file is not installed on the system.</li>
<li>When a font library is not available, the local JVM will replace it with some default fonts, and this could lead to
various side effects, such as totally different text appearance or truncated pieces of text.</li>
</ul>
It's obviously that running a report in this kind of approach becomes completely dependent on the local environment, and one
have to ensure that required font files are installed on the machine where the report is run. If they aren't, they should be installed first.
And that's what should be done on every machine running the report. Quite a little bit embarrassing, isn't it.
<br>
Therefore, this is not the best way to control fonts in JasperReports. A much better one is due to the extension points support,
available in JasperReports. Font files can be
provided as library extensions. In a very simple manner, making a font extension consists in putting various True Type Font files
in a JAR file together with a properties file describing the content of the JAR, and an XML file defining relationships between fonts
and locales.
<br>
<br>
<b>Font Extensions Step By Step</b>
<br>
<br>
Let's take a look into the <span class="code"><code>/demo/fonts</code></span> directory. It contains the DejaVu font extension available as default font for all
samples shipped with the JasperReports project distribution package.
<br>
As known from extensions support, any JasperReports extension provides a <span class="code"><code>jasperreports_extension.properties</code></span> file in its root
package, required by the JasperReports extension mechanism. This file is used to describe the content of the extension JAR file and consists in
the following lines:
<br>
<br>
<span class="code"><code>
net.sf.jasperreports.extension.registry.factory.simple.font.families=net.sf.jasperreports.engine.fonts.SimpleFontExtensionsRegistryFactory
<br>
net.sf.jasperreports.extension.simple.font.families.dejavu=net/sf/jasperreports/fonts/fonts.xml
</code></span>
<br>
<br>
The <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/fonts/SimpleFontExtensionsRegistryFactory.html" target="_blank">SimpleFontExtensionsRegistryFactory</a></span> class represents
an implementation of the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/extensions/ExtensionsRegistryFactory.html" target="_blank">ExtensionsRegistryFactory</a></span> interface, used to
instantiate a font extension registry.
<br>
The extension registry obtained from the factory is able to return a list of actual extension point implementations based on extension point class type.
<br>
The second line provides the path to the XML file describing the actual font extension. The XML file in this case is named <span class="code"><code>fonts.xml</code></span>.
<br>
<br>
The main unit in the <span class="code"><code>fonts.xml</code></span> file is the <span class="code"><code><fontFamily/></code></span> element. A font family is an object instance which
extends the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/fonts/FontFamily.html" target="_blank">FontFamily</a></span> public interface. This is the point where
font extensions can be connected with the JasperReports engine.
<br>
Font families described in the <span class="code"><code>fonts.xml</code></span> file consist in up to 4 font faces: normal, <b>bold</b>, <i>italic</i> and <b><i>bolditalic</i></b>.
A font face is described by the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/fonts/FontFace.html" target="_blank">FontFace</a></span> interface.
<br>
<br>
In order to completely describe a font family extension, one have to indicate the mapping between the font faces and font files,
the <span class="code"><code>pdfEncoding</code></span> and <span class="code"><code>pdfEmbedded</code></span> attributes, equivalent font face names available for dedicated exporters,
such as the HTML exporter) and a list of supported locales, because font files usually support only certain languages.
<br>
<br>
The <span class="code"><code>fonts.xml</code></span> file includes 3 different font families:
<ul>
<li>
<span class="code"><code>DejaVu Sans</code></span>
</li>
<li>
<span class="code"><code>DejaVu Serif</code></span>
</li>
<li>
<span class="code"><code>DejaVu Sans Mono</code></span>
</li>
</ul>
and some mappings for logical JVM fonts available for HTML exporters:
<ul>
<li>
<span class="code"><code>SansSerif</code></span>
</li>
<li>
<span class="code"><code>Serif</code></span>
</li>
<li>
<span class="code"><code>Monospaced</code></span>
</li>
</ul>
<br>
Let's take a look at the DejaVu Sans family. All the font family settings already discussed can be found in the example below:
<pre>
<fontFamily name="DejaVu Sans">
<normal>net/sf/jasperreports/fonts/dejavu/DejaVuSans.ttf</normal>
<bold>net/sf/jasperreports/fonts/dejavu/DejaVuSans-Bold.ttf</bold>
<italic>net/sf/jasperreports/fonts/dejavu/DejaVuSans-Oblique.ttf</italic>
<boldItalic>net/sf/jasperreports/fonts/dejavu/DejaVuSans-BoldOblique.ttf</boldItalic>
<pdfEncoding>Identity-H</pdfEncoding>
<pdfEmbedded>true</pdfEmbedded>
<exportFonts>
<export key="net.sf.jasperreports.html">'DejaVu Sans', Arial, Helvetica, sans-serif</export>
<export key="net.sf.jasperreports.xhtml">'DejaVu Sans', Arial, Helvetica, sans-serif</export>
</exportFonts>
<!--
<locales>
<locale>en_US</locale>
<locale>de_DE</locale>
</locales>
-->
</fontFamily></pre>
The <span class="code"><code>name</code></span> attribute and the <span class="code"><code><normal/></code></span> font face represent required elements in a font family definition,
while all the others are optional.
<br>
The name of the font family will be used as the <span class="code"><code>fontName</code></span> attribute of the text element or style in the report
template. The <span class="code"><code>fontName</code></span> together with the <span class="code"><code>isBold</code></span> and <span class="code"><code>isItalic</code></span> attributes of the
text field or style in the report help to locate and load the appropriate font face from the family. If a particular font
face is not present or declared in the family, then the normal font face will be used instead.
<br>
<br>
In the example above we can see the mappings for the <b>bold</b>, <i>italic</i> and <b><i>bolditalic</i></b> font styles are also present.
The <span class="code"><code><exportFonts/></code></span> tag instructs the HTML exporters
to correlate this font family with other HTML supported font families, such as Arial, Helvetica, sans-serif.
<br>
<br>
The <span class="code"><code><locales/></code></span> contains a list of supported locales. This block being commented, the engine will try to apply this font family
for any locale, without taking into account if the font file really provides support for that locale. If a particular locale is not supported, errors might
occur at runtime and characters might be misrepresented.
<br>
However, if a given font family needs to be represented for locales supported by different font files, one can define separate font families in the XML file,
having the same name but with differing <span class="code"><code><locales/></code></span> tag. This feature is very useful when the same report has to be run in both
Japanese and Chinese, because there is no TTF file that simultaneously supports these two languages.
<br>
<br>
The <span class="code"><code><pdfEncoding/></code></span> and <span class="code"><code><pdfEmbedded/></code></span> are used to specify the PDF encoding attribute and the PDF embedding flag, and
people are strongly encouraged to use them instead of deprecated <span class="code"><code>pdfEncoding</code></span> and <span class="code"><code>pdfEmbedded</code></span> attributes available in the JRXML
<span class="code"><code><font/></code></span> tag.
<br>
<br>
Now, let's take a look at logical JVM fonts mappings:
<pre>
<fontFamily name="SansSerif">
<exportFonts>
<export key="net.sf.jasperreports.html">'DejaVu Sans', Arial, Helvetica, sans-serif</export>
<export key="net.sf.jasperreports.xhtml">'DejaVu Sans', Arial, Helvetica, sans-serif</export>
</exportFonts>
</fontFamily>
<fontFamily name="Serif">
<exportFonts>
<export key="net.sf.jasperreports.html">'DejaVu Serif', 'Times New Roman', Times, serif</export>
<export key="net.sf.jasperreports.xhtml">'DejaVu Serif', 'Times New Roman', Times, serif</export>
</exportFonts>
</fontFamily>
<fontFamily name="Monospaced">
<exportFonts>
<export key="net.sf.jasperreports.html">'DejaVu Sans Mono', 'Courier New', Courier, monospace</export>
<export key="net.sf.jasperreports.xhtml">'DejaVu Sans Mono', 'Courier New', Courier, monospace</export>
</exportFonts>
</fontFamily></pre>
Here the DejaVu font families are added to the font families list available for HTML at export time.
<br>
<br>
Once you have the TTF files, the <span class="code"><code>jasperreports_extension.properties</code></span> and <span class="code"><code>fonts.xml</code></span> files,
you can pack them together in a JAR file, and then put the JAR in your application's classpath,
in order to make the new fonts available to your reports, wherever the application might run.
<br>
<br>
For more details about deploying fonts as extensions, you can take a look at the
<a href="#fonts" target="_blank" class="element">Fonts</a> sample provided with the JasperReports project distribution
package, which adds one more font extension for another open source font called Gentium. Running the
sample using the <span class="code"><code>> ant clean javac compile fontsXml</code></span> command will generate in the
<span class="code"><code>demo/samples/fonts/build/reports</code></span> a font extension xml file named <span class="code"><code>fonts.xml</code></span>. This file contains all font families
available in the already installed font extensions.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
</table>
<br>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td>
<hr size="1">
</td>
</tr>
<tr>
<td align="center"><span class="copy">© 2001-2010 Jaspersoft Corporation <a href="http://www.jaspersoft.com" target="_blank" class="copy">www.jaspersoft.com</a></span></td>
</tr>
</table>
</body>
</html>
