<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>forms</name>
  <title>PDF Forms Sample</title>
  <description>Shows how to generate editable PDF content using JasperReports.</description>

  <mainFeature ref="pdfforms"/>
  
  <!-- FIXME -->
  
  <feature name="pdfforms" title="Generating Editable PDF Content">
    <description>
Shows how specific PDF export properties can be used in order to generate editable PDF content.
    </description>
    <since>6.12.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>.
    <content>
<subtitle name="overview">PDF Forms and Input Fields</subtitle>
<br/>
<br/>
The content of a PDF document can be edited inside a PDF form that contains various input fields such as textboxes, lists, 
comboboxes, checkboxes, radio groups, etc. Using the JasperReports library, one can generate these input fields by setting specific 
custom properties in the report. In the following sections we will see how these properties can be set and how they work in conjunction to 
generate editable content in PDF documents.
<br/>
<br/>
<subtitle name="input_field_type">Input Field Types</subtitle>
<br/>
<br/>
In order to determine the appropriate content and layout of an input field we need to know its type first. The JasperReports library 
offers support for the following types:
<ul>
<li>Textbox</li>
<li>List</li>
<li>Combobox</li>
<li>Checkbox</li>
<li>Radio groups</li>
</ul>
The field type can be specified in the <a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.type">net.sf.jasperreports.export.pdf.field.type</a> property, 
that accepts the following values:
<ul>
<li><code>Text</code> - specifies a textbox; this type of input field can be applied only to text elements (static text and textfield) in JasperReports</li>
<li><code>Combo</code> - specifies a combobox</li>
<li><code>List</code> - specifies a list</li>
<li><code>Check</code> - specifies a checkbox</li>
<li><code>Radio</code> - specifies a radio group</li>
</ul>
Each input field needs a unique identifier within the PDF form. This can be set using the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.name">net.sf.jasperreports.export.pdf.field.name</a> element property. 
In case this is not set, the field name is generated using the report element UUID.
<br/>
<br/>
The background color, forecolor and text formatting inside a generated input field are inherited from the JasperReports element. For the border style we 
need to set the following property, with values compatible with PDF border styles: 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.border.style">net.sf.jasperreports.export.pdf.field.border.style</a>.<br/>
Possible values are:
<ul>
<li><code>Solid</code> - solid border</li>
<li><code>Dashed</code> - dashed border</li>
<li><code>Beveled</code> - beveled border</li>
<li><code>Inset</code> - inset border</li>
<li><code>Underline</code> - underline border</li>
</ul>
When this property is not set, the border is inherited from the element's pen style: if the pen style is 
'<code>Dashed</code>', this style will be applied, otherwise the pen '<code>Solid</code>' style will be considered by default.<br/>
The border thickness is rounded and recalculated to have one of the following values compatible with PDF: [1,2,3].
In case we need some input field content to be read-only, we can set the <a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.read.only">net.sf.jasperreports.export.pdf.field.read.only</a> 
flag for that element.
<br/>
<br/>
<b>Example:</b>
<pre><![CDATA[
<reportElement positionType="Float" mode="Opaque" x="0" y="0" width="25" height="25">
  <property name="net.sf.jasperreports.export.pdf.field.type" value="Check"/>
  <property name="net.sf.jasperreports.export.pdf.field.border.style" value="Beveled"/>
  <property name="net.sf.jasperreports.export.pdf.field.read.only" value="true"/>
</reportElement>]]></pre>
<subtitle name="textbox">Text Input Fields</subtitle>
<br/>
<br/>
Textboxes are text input fields. They can be either single line or multi line textboxes. To specify which kind of textbox is considered, we can set the following flag property per report element: 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.text.multiline">net.sf.jasperreports.export.pdf.field.text.multiline</a>. 
The initial text content of the input field is provided by the <a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.value">net.sf.jasperreports.export.pdf.field.value</a> custom property
and in case that one is missing, then the actual text content of the JasperReports text element is used instead.
<br/>
<br/>
<b>Example:</b>
<pre><![CDATA[
<reportElement positionType="Float" mode="Opaque" x="250" y="0" width="200" height="45" forecolor="#FFFF00" backcolor="#0000FF">
  <property name="net.sf.jasperreports.export.pdf.field.type" value="Text"/>
  <property name="net.sf.jasperreports.export.pdf.field.text.multiline" value="true"/>
  <property name="net.sf.jasperreports.print.keep.full.text" value="true"/>
  <propertyExpression name="net.sf.jasperreports.export.pdf.field.value">"This\nis a multi\nline text inside a single line text field."</propertyExpression>
</reportElement>]]></pre>
<subtitle name="textbox">List and Combobox Input Fields</subtitle>
<br/>
<br/>
List and combobox input fields can be populated by setting the following property:
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.choices">net.sf.jasperreports.export.pdf.field.choices</a>. 
Its value contains list items separated by a special character or set of characters provided by the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.choice.separators">net.sf.jasperreports.export.pdf.field.choice.separators</a> property. 
If not set, the default separator is '|'.
<br/>
<br/>
<b>Example:</b>
<pre><![CDATA[
<reportElement positionType="Float" mode="Opaque" x="0" y="0" width="200" height="95" forecolor="#00FFFF" backcolor="#00FF00">
  <property name="net.sf.jasperreports.export.pdf.field.type" value="List"/>
  <property name="net.sf.jasperreports.export.pdf.field.choice.separators" value=","/>
  <property name="net.sf.jasperreports.export.pdf.field.choices" value="Un,Deux,Trois,Quatre,Cinq"/>
</reportElement>]]></pre>
In case we need the textbox in the combobox field to be editable, we can set the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.combo.edit">net.sf.jasperreports.export.pdf.field.combo.edit</a> property per 
combobox element, while the a preselected value can be set using the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.value">net.sf.jasperreports.export.pdf.field.value</a> property:
<pre><![CDATA[
<reportElement positionType="Float" mode="Opaque" x="250" y="0" width="200" height="25" forecolor="#0000FF" backcolor="#FFFF00">
  <property name="net.sf.jasperreports.export.pdf.field.type" value="Combo"/>
  <property name="net.sf.jasperreports.export.pdf.field.choices" value="One|Two|Three|Four|Five"/>
  <property name="net.sf.jasperreports.export.pdf.field.value" value="Four"/>
  <property name="net.sf.jasperreports.export.pdf.field.combo.edit" value="true"/>
</reportElement>]]></pre>
<subtitle name="checkboxes">Checkbox Input Field</subtitle>
<br/>
<br/>
In order to properly set a checkbox we need to know how it's decorated and whether it's checked or no. We can set the checkbox appearance by using the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.check.type">net.sf.jasperreports.export.pdf.field.check.type</a> property 
with the following possible values:
<ul>
<li><code>Check</code> - specifies a checkbox type decoration</li>
<li><code>Circle</code> - specifies a circle tipe decoration</li>
<li><code>Cross</code> - specifies a cross type decoration</li>
<li><code>Diamond</code> - specifies a diamond type decoration</li>
<li><code>Square</code> - specifies a square type decoration</li>
<li><code>Star</code> - specifies a star type decoration</li>
</ul>
To indicate if the checkbox is checked when the PDF document is open, we can use the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.checked">net.sf.jasperreports.export.pdf.field.checked</a> property, 
as in the following example:
<pre><![CDATA[
<reportElement positionType="Float" mode="Opaque" x="0" y="0" width="25" height="25">
  <property name="net.sf.jasperreports.export.pdf.field.type" value="Check"/>
  <property name="net.sf.jasperreports.export.pdf.field.check.type" value="Square"/>
  <property name="net.sf.jasperreports.export.pdf.field.checked" value="true"/>
</reportElement>]]></pre>
<subtitle name="radiogroups">Radio Groups</subtitle>
<br/>
<br/>
Radio groups are radio option input fields grouped together so that only a single option can be selected at a time. To group together 
several radio options we can use the <a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.name">net.sf.jasperreports.export.pdf.field.name</a> property. 
By assigning the same name for multiple JasperReports elements, they will be automatically grouped as radio options. To decorate these radio elements we can use the same 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.check.type">net.sf.jasperreports.export.pdf.field.check.type</a> property with the same possible 
values as for checkboxes. Also, to indicate which option is selected when opening the document, we can use the 
<a href="../../config.reference.html#net.sf.jasperreports.export.pdf.field.checked">net.sf.jasperreports.export.pdf.field.checked</a> property.
<br/>
<br/>
<b>Example:</b>
<pre><![CDATA[
<textField>
  <reportElement positionType="Float" mode="Opaque" x="250" y="0" width="25" height="25">
    <property name="net.sf.jasperreports.export.pdf.field.name" value="MyRadioGroup"/>
    <property name="net.sf.jasperreports.export.pdf.field.type" value="Radio"/>
    <property name="net.sf.jasperreports.export.pdf.field.check.type" value="Check"/>
  </reportElement>
  <box>
    <pen lineWidth="1"/>
  </box>
  <textFieldExpression><![CDATA["This text does not matter in PDF export."]] ></textFieldExpression>
</textField>
<textField>
  <reportElement positionType="Float" mode="Opaque" x="250" y="0" width="25" height="25">
    <property name="net.sf.jasperreports.export.pdf.field.name" value="MyRadioGroup"/>
    <property name="net.sf.jasperreports.export.pdf.field.type" value="Radio"/>
    <property name="net.sf.jasperreports.export.pdf.field.check.type" value="Circle"/>
    <property name="net.sf.jasperreports.export.pdf.field.checked" value="true"/>
  </reportElement>
  <box>
    <pen lineWidth="1"/>
  </box>
  <textFieldExpression><![CDATA["This text does not matter in PDF export."]] ></textFieldExpression>
</textField>
<textField>
  <reportElement positionType="Float" mode="Opaque" x="250" y="0" width="25" height="25">
    <property name="net.sf.jasperreports.export.pdf.field.name" value="MyRadioGroup"/>
    <property name="net.sf.jasperreports.export.pdf.field.type" value="Radio"/>
    <property name="net.sf.jasperreports.export.pdf.field.check.type" value="Cross"/>
  </reportElement>
  <box>
    <pen lineWidth="1"/>
  </box>
  <textFieldExpression><![CDATA["This text does not matter in PDF export."]] ></textFieldExpression>
</textField>
<textField>
  <reportElement positionType="Float" mode="Opaque" x="250" y="0" width="25" height="25">
    <property name="net.sf.jasperreports.export.pdf.field.name" value="MyRadioGroup"/>
    <property name="net.sf.jasperreports.export.pdf.field.type" value="Radio"/>
    <property name="net.sf.jasperreports.export.pdf.field.check.type" value="Diamond"/>
  </reportElement>
  <box>
    <pen lineWidth="1"/>
  </box>
  <textFieldExpression><![CDATA["This text does not matter in PDF export."]] ></textFieldExpression>
</textField>
<textField>
  <reportElement positionType="Float" mode="Opaque" x="250" y="0" width="25" height="25">
    <property name="net.sf.jasperreports.export.pdf.field.name" value="MyRadioGroup"/>
    <property name="net.sf.jasperreports.export.pdf.field.type" value="Radio"/>
    <property name="net.sf.jasperreports.export.pdf.field.check.type" value="Square"/>
  </reportElement>
  <box>
    <pen lineWidth="1"/>
  </box>
  <textFieldExpression><![CDATA["This text does not matter in PDF export."]] ></textFieldExpression>
</textField>]]></pre>
<subtitle name="limitations">Known Limitations and Issues</subtitle>
<ol>
<li>Radio groups cannot overflow on the next page.</li>
<li>Radio group options cannot be made read-only.</li>
</ol>
<subtitle name="runSample">Running the Sample</subtitle>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/forms</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/forms/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer. You could open the PDF generated document and see how it differs from other generated outputs.
    </content>
  </feature>

</sample>
