Class FormChoice
- java.lang.Object
-
- org.faceless.pdf2.FormElement
-
- org.faceless.pdf2.FormChoice
-
- All Implemented Interfaces:
java.lang.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 bygetOptions()
. 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 elementForm 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 menustatic 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 newFormChoice
element with no annotations.FormChoice(int type, PDFPage page, float x1, float y1, float x2, float y2)
Create a newFormChoice
element with an annotation at the specified location.
-
Method Summary
All Methods Instance Methods Concrete Methods 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 pageprotected java.lang.Object
clone()
java.lang.String
getDefaultValue()
Return the value this choice field resets to when aPDFAction.formReset()
occurs.java.util.Map<java.lang.String,java.lang.String>
getOptions()
Return aMap
containing the options for this choice fieldint[]
getSelectedIndices()
Return an array of integers showing which entries in thegetOptions()
map are selected.int
getType()
Return the type of choice field this object represents - one ofTYPE_SCROLLABLE
,TYPE_MULTISCROLLABLE
,TYPE_DROPDOWN
orTYPE_COMBO
java.lang.String
getValue()
Return the current value of the choice field.boolean
isImmediatelyCommitted()
Return whether the field is immediatley committed, as set bysetImmediatelyCommitted(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 bysetSpellCheck(boolean)
void
putLiteral(java.lang.String key, java.lang.String tokens)
Put a literal token sequnce.void
rebuild()
Cause the annotation list to be rebuilt.void
setDefaultValue(java.lang.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 thegetOptions()
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(java.lang.String value)
Set the value of this choice field.java.lang.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
-
-
-
-
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 newFormChoice
element with no annotations. Annotations should be added via theaddAnnotation
method.- Since:
- 1.1.26
-
FormChoice
public FormChoice(int type, PDFPage page, float x1, float y1, float x2, float y2)
Create a newFormChoice
element with an annotation at the specified location. Identical to callingFormChoice choice = new FormChoice(type); choice.addAnnotation(page, x1, y1, x2, y2);
- Parameters:
type
- the type of annotationpage
- thePDFPage
to place the annotation onx1
- the left-most X co-ordinate of the annotationy1
- the bottom-most Y co-ordinate of the annotationx2
- the right-most X co-ordinate of the annotationy2
- 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
- thePDFPage
to place the annotation onx1
- the left-most X co-ordinate of the annotationy1
- the bottom-most Y co-ordinate of the annotationx2
- the right-most X co-ordinate of the annotationy2
- 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 ofTYPE_SCROLLABLE
,TYPE_MULTISCROLLABLE
,TYPE_DROPDOWN
orTYPE_COMBO
- Returns:
- the type of choice field
-
getOptions
public java.util.Map<java.lang.String,java.lang.String> getOptions()
Return a
Map
containing the options for this choice fieldA 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 dochoice.getOptions().put("Red", null)
orchoice.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 bothkey
andvalue
must beString
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 bysetImmediatelyCommitted(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 thegetOptions()
map are selected. The returned array will have a length of zero if no value is selected or aTYPE_COMBO
field has a custom value, otherwise the returned array will typically have a single element - the exception beingTYPE_MULTISCROLLABLE
fields.- Since:
- 2.9
-
setSelectedIndices
public void setSelectedIndices(int[] vals)
Set which entries in thegetOptions()
map are selected. Unless the list is aTYPE_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(java.lang.String value)
Set the value of this choice field. ForTYPE_COMBO
fields, the value may be anything, otherwise the value must exist in thegetOptions().values()
set. ForTYPE_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(java.lang.String value)
Set the default value of this choice field. Identical tosetValue(java.lang.String, java.lang.String)
except this is the value the field reverts to when aPDFAction.formReset()
action is called.- Parameters:
value
- the value to set the field to when the form is reset
-
getValue
public java.lang.String getValue()
Return the current value of the choice field. SeesetValue(java.lang.String, java.lang.String)
for a description of the value that is returned by this method- Specified by:
getValue
in classFormElement
- Returns:
- the value of this choice field
-
getDefaultValue
public java.lang.String getDefaultValue()
Return the value this choice field resets to when aPDFAction.formReset()
occurs. SeesetValue(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 classFormElement
-
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 bysetSpellCheck(boolean)
- Since:
- 2.11.14
-
toString
public java.lang.String toString()
-
putLiteral
public void putLiteral(java.lang.String key, java.lang.String tokens)
Put a literal token sequnce. For debugging- Parameters:
key
- the keytokens
- the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.
-
clone
protected java.lang.Object clone()
- Overrides:
clone
in classjava.lang.Object
-
-