Package org.faceless.pdf2

Class FormChoice

java.lang.Object

org.faceless.pdf2.FormElement

org.faceless.pdf2.FormChoice

All Implemented Interfaces:

Cloneable

public final class FormChoice
extends FormElement

A "ListBox" type of form element, where the user can select an entry off a list of several predefined options.

Several variations of this type of field are available:

TYPE_DROPDOWN	A dropdown list, where a single item can be selected
TYPE_COMBO	Identical to a dropdown list, but the user can type in their own value as well as select one off a list
TYPE_SCROLLABLE	A scrollable list, where the user can see several options on the screen at once but select only one
TYPE_MULTISCROLLABLE	Identical to a SCROLLABLE list, but mutiple options can be selected at once

For all these lists, the options are specified by adding values to the Map returned by getOptions(). The values are displayed in the order they're added to the Map.

Here's an example creating a simple list of values:

   Form form = pdf.getForm();
   FormChoice colors = new FormChoice(FormChoice.TYPE_SCROLLABLE, page, 100,100,300,300);
   Map vals = colors.getOptions();
   vals.put("Red", null);
   vals.put("Green", null);
   vals.put("Blue", null);
   colors.setValue("Green");
   form.addElement("FavoriteColor", colors);
 

and here's an example showing how to retrieve the value of an element

   Form form = pdf.getForm();
   FormChoice choice = (FormChoice)form.getElement("FavoriteColor");
   String value = choice.getValue();  // May be null
 

Since:

1.1.23

Field Summary

Fields

Modifier and Type	Field	Description
static int	TYPE_COMBO	A type passed to the constructor representing a dropdown list where the value can also be edited like a text field.
static int	TYPE_DROPDOWN	A type passed to the constructor representing a dropdown list, similar to a drop-down menu
static int	TYPE_MULTISCROLLABLE	A type passed to the constructor representing a scollable list, which displays one or more lines at once.
static int	TYPE_SCROLLABLE	A type passed to the constructor representing a scollable list, which displays one or more lines at once.

Constructor Summary

Constructors

Constructor	Description
FormChoice(int type)	Create a new FormChoice element with no annotations.
FormChoice(int type, PDFPage page, float x1, float y1, float x2, float y2)	Create a new FormChoice element with an annotation at the specified location.

Method Summary

Modifier and Type	Method	Description
WidgetAnnotation	addAnnotation(PDFPage page, float x1, float y1, float x2, float y2)	Add an annotation for this element at the specified location on the page
protected Object	clone()
String	getDefaultValue()	Return the value this choice field resets to when a PDFAction.formReset() occurs.
Map<String,String>	getOptions()	Return a Map containing the options for this choice field
int[]	getSelectedIndices()	Return an array of integers showing which entries in the getOptions() map are selected.
int	getType()	Return the type of choice field this object represents - one of TYPE_SCROLLABLE, TYPE_MULTISCROLLABLE, TYPE_DROPDOWN or TYPE_COMBO
String	getValue()	Return the current value of the choice field.
boolean	isImmediatelyCommitted()	Return whether the field is immediatley committed, as set by setImmediatelyCommitted(boolean)
boolean	isRTL()	Return true if this text field is marked as right-to-left.
boolean	isSpellCheck()	Return the value of the "spell check" flag, as set by setSpellCheck(boolean)
void	rebuild()	Cause the annotation list to be rebuilt.
void	setDefaultValue(String value)	Set the default value of this choice field.
void	setImmediatelyCommitted(boolean update)	Set whether changes to this Choice field are made immediately the new item is chosen (true) or whether the change is made when the field loses focus (false).
void	setRTL(boolean rtl)	Set the field to be right-to-left.
void	setSelectedIndices(int[] vals)	Set which entries in the getOptions() map are selected.
void	setSpellCheck(boolean spellcheck)	Set the "spell check" flag on the field, which controls whether Acrobat will run its spell-checker on the field.
void	setValue(String value)	Set the value of this choice field.
String	toString()

Methods inherited from class org.faceless.pdf2.FormElement

addPropertyChangeListener, duplicate, flatten, getAction, getAnnotation, getAnnotations, getDescription, getForm, isReadOnly, isRequired, isSubmitted, removePropertyChangeListener, setAction, setDescription, setReadOnly, setRequired, setSubmitted

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE_DROPDOWN

public static final int TYPE_DROPDOWN

A type passed to the constructor representing a dropdown list, similar to a drop-down menu

TYPE_SCROLLABLE

public static final int TYPE_SCROLLABLE

A type passed to the constructor representing a scollable list, which displays one or more lines at once.

See Also:

Constant Field Values

TYPE_MULTISCROLLABLE

public static final int TYPE_MULTISCROLLABLE

A type passed to the constructor representing a scollable list, which displays one or more lines at once. Multiple items can be selected

Since:

2.0

TYPE_COMBO

public static final int TYPE_COMBO

A type passed to the constructor representing a dropdown list where the value can also be edited like a text field.

Constructor Detail

FormChoice

public FormChoice(int type)

Create a new FormChoice element with no annotations. Annotations should be added via the addAnnotation method.

Since:

1.1.26

FormChoice

public FormChoice(int type,
                  PDFPage page,
                  float x1,
                  float y1,
                  float x2,
                  float y2)

Create a new FormChoice element with an annotation at the specified location. Identical to calling

   FormChoice choice = new FormChoice(type);
   choice.addAnnotation(page, x1, y1, x2, y2);
 

Parameters:

type - the type of annotation

page - the PDFPage to place the annotation on

x1 - the left-most X co-ordinate of the annotation

y1 - the bottom-most Y co-ordinate of the annotation

x2 - the right-most X co-ordinate of the annotation

y2 - the top-most Y co-ordinate of the annotation

Since:

2.0 (a similar constructor existed from 1.1.26, but with the first two arguments swapped)

Method Detail

addAnnotation

public WidgetAnnotation addAnnotation(PDFPage page,
                                      float x1,
                                      float y1,
                                      float x2,
                                      float y2)

Add an annotation for this element at the specified location on the page

Parameters:

page - the PDFPage to place the annotation on

x1 - the left-most X co-ordinate of the annotation

y1 - the bottom-most Y co-ordinate of the annotation

x2 - the right-most X co-ordinate of the annotation

y2 - the top-most Y co-ordinate of the annotation

Since:

2.0

getType

public int getType()

Return the type of choice field this object represents - one of TYPE_SCROLLABLE, TYPE_MULTISCROLLABLE, TYPE_DROPDOWN or TYPE_COMBO

Returns:

the type of choice field

getOptions

public Map<String,String> getOptions()

Return a Map containing the options for this choice field

A Map contains keys and their corresponding values, which is the way the choice fields are done in PDF (and HTML too). They key is displayed to the user, and the value, if specified, is what's included when the form is submitted. So, for example, the line choice.getOptions().put("Red","1") will display the value "Red" on screen, but send the value of "1" when the form is submitted. If the submitted value should be the same as the displayed value, just do choice.getOptions().put("Red", null) or choice.getOptions().put("Red", "Red").

Values are displayed in the field in the order that they are added to the Map, key may not be null, and both key and value must be String objects.

setImmediatelyCommitted

public void setImmediatelyCommitted(boolean update)

Set whether changes to this Choice field are made immediately the new item is chosen (true) or whether the change is made when the field loses focus (false). Only makes a difference in Acrobat 6 or later, although can safely be used with earlier viewers.

Since:

2.0

isImmediatelyCommitted

public boolean isImmediatelyCommitted()

Return whether the field is immediatley committed, as set by setImmediatelyCommitted(boolean)

Since:

2.0

isRTL

public boolean isRTL()

Return true if this text field is marked as right-to-left. This is an undocumented and non-standard flag, but is used by Acrobat to create RTL fields.

Since:

2.20.3

setRTL

public void setRTL(boolean rtl)

Set the field to be right-to-left. This is an undocumented and non-standard flag, but is used by Acrobat to create RTL fields.

Since:

2.20.3

getSelectedIndices

public int[] getSelectedIndices()

Return an array of integers showing which entries in the getOptions() map are selected. The returned array will have a length of zero if no value is selected or a TYPE_COMBO field has a custom value, otherwise the returned array will typically have a single element - the exception being TYPE_MULTISCROLLABLE fields.

Since:

2.9

setSelectedIndices

public void setSelectedIndices(int[] vals)

Set which entries in the getOptions() map are selected. Unless the list is a TYPE_MULTISCROLLABLE then the array must have either zero or one elements - multi-scrollable lists may have more.

Parameters:

vals - an array of zero or more indices which are to be marked as selected

Since:

2.9

setValue

public void setValue(String value)

Set the value of this choice field. For TYPE_COMBO fields, the value may be anything, otherwise the value must exist in the getOptions().values() set. For TYPE_MULTISCROLLABLE lists, multiple items can be selected by separating them with a newline, eg. "Tuesday\nWednesday\nThursday"

Parameters:

value - the value to set the field to

setDefaultValue

public void setDefaultValue(String value)

Set the default value of this choice field. Identical to setValue(java.lang.String, java.lang.String) except this is the value the field reverts to when a PDFAction.formReset() action is called.

Parameters:

value - the value to set the field to when the form is reset

getValue

public String getValue()

Return the current value of the choice field. See setValue(java.lang.String, java.lang.String) for a description of the value that is returned by this method

Specified by:

getValue in class FormElement

Returns:

the value of this choice field

getDefaultValue

public String getDefaultValue()

Return the value this choice field resets to when a PDFAction.formReset() occurs. See setValue(java.lang.String, java.lang.String) for a description of the value that is returned by this method

Returns:

the value this choice field reverts to when the form is reset

rebuild

public void rebuild()

Description copied from class: FormElement

Cause the annotation list to be rebuilt. Unless you're rendering the annotation using the viewer, it's not necessary to call this method.

Overrides:

rebuild in class FormElement

setSpellCheck

public void setSpellCheck(boolean spellcheck)

Set the "spell check" flag on the field, which controls whether Acrobat will run its spell-checker on the field. This flag has no other effect.

Parameters:

spellcheck - whether to spell-check the field (true, the default) or not (false)

Since:

2.11.14

isSpellCheck

public boolean isSpellCheck()

Return the value of the "spell check" flag, as set by setSpellCheck(boolean)

Since:

2.11.14

toString

public String toString()

clone

protected Object clone()

Overrides:

clone in class Object