Form (Smack 4.3.0 API)

java.lang.Object
- org.jivesoftware.smackx.xdata.Form

Direct Known Subclasses:

ConfigureForm, SubscribeForm
```
public class Form
extends Object
```
Represents a Form for gathering data. The form could be of the following types:
- form → Indicates a form to fill out.
- submit → The form is filled out, and this is the data that is being returned from the form.
- cancel → The form was cancelled. Tell the asker that piece of information.
- result → Data results being returned from a search, or some other query.
Depending of the form's type different operations are available. For example, it's only possible to set answers if the form is of type "submit".
See Also:

XEP-0004 Data Forms

Constructor Summary

Constructors
Constructor and Description
`Form(DataForm.Type type)` Creates a new Form of a given type from scratch.
`Form(DataForm dataForm)` Creates a new Form that will wrap an existing DataForm.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addField(FormField field)` Adds a new field to complete as part of the form.
`Form`	`createAnswerForm()` Returns a new Form to submit the completed values.
`DataForm`	`getDataFormToSend()` Returns a DataForm that serves to send this Form to the server.
`FormField`	`getField(String variable)` Returns the field of the form whose variable matches the specified variable.
`List<FormField>`	`getFields()` Returns a List of the fields that are part of the form.
`static Form`	`getFormFrom(Stanza packet)` Returns a new ReportedData if the stanza is used for gathering data and includes an extension that matches the elementName and namespace "x","jabber:x:data".
`String`	`getInstructions()` Returns the instructions that explain how to fill out the form and what the form is about.
`String`	`getTitle()` Returns the description of the data.
`DataForm.Type`	`getType()` Returns the meaning of the data within the context.
`boolean`	`hasField(String variable)` Check if a field with the given variable exists.
`void`	`setAnswer(String variable, boolean value)` Sets a new boolean value to a given form's field.
`void`	`setAnswer(String variable, double value)` Sets a new double value to a given form's field.
`void`	`setAnswer(String variable, float value)` Sets a new float value to a given form's field.
`void`	`setAnswer(String variable, int value)` Sets a new int value to a given form's field.
`void`	`setAnswer(String variable, List<? extends CharSequence> values)` Sets a new values to a given form's field.
`void`	`setAnswer(String variable, long value)` Sets a new long value to a given form's field.
`void`	`setAnswer(String variable, String value)` Sets a new String value to a given form's field.
`void`	`setDefaultAnswer(String variable)` Sets the default value as the value of a given form's field.
`void`	`setInstructions(String instructions)` Sets instructions that explain how to fill out the form and what the form is about.
`void`	`setTitle(String title)` Sets the description of the data.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Form
```
public Form(DataForm dataForm)
```
    Creates a new Form that will wrap an existing DataForm. The wrapped DataForm must be used for gathering data.
    
    Parameters:
    
    dataForm - the data form used for gathering data.
  - Form
```
public Form(DataForm.Type type)
```
    Creates a new Form of a given type from scratch.
    
    Parameters:
    
    type - the form's type (e.g. form, submit,cancel,result).
- Method Detail
  - getFormFrom
```
public static Form getFormFrom(Stanza packet)
```
    Returns a new ReportedData if the stanza is used for gathering data and includes an extension that matches the elementName and namespace "x","jabber:x:data".
    
    Parameters:
    
    packet - the stanza used for gathering data.
    
    Returns:
    
    the data form parsed from the stanza or null if there was not a form in the packet.
  - addField
```
public void addField(FormField field)
```
    Adds a new field to complete as part of the form.
    
    Parameters:
    
    field - the field to complete.
  - setAnswer
```
public void setAnswer(String variable,
                      String value)
```
    Sets a new String value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.
    If the value to set to the field is not a basic type (e.g. String, boolean, int, etc.) you can use this message where the String value is the String representation of the object.
    
    Parameters:
    
    variable - the variable name that was completed.
    
    value - the String value that was answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type..
  - setAnswer
```
public void setAnswer(String variable,
                      int value)
```
    Sets a new int value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.
    
    Parameters:
    
    variable - the variable name that was completed.
    
    value - the int value that was answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.
  - setAnswer
```
public void setAnswer(String variable,
                      long value)
```
    Sets a new long value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.
    
    Parameters:
    
    variable - the variable name that was completed.
    
    value - the long value that was answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.
  - setAnswer
```
public void setAnswer(String variable,
                      float value)
```
    Sets a new float value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.
    
    Parameters:
    
    variable - the variable name that was completed.
    
    value - the float value that was answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.
  - setAnswer
```
public void setAnswer(String variable,
                      double value)
```
    Sets a new double value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.
    
    Parameters:
    
    variable - the variable name that was completed.
    
    value - the double value that was answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.
  - setAnswer
```
public void setAnswer(String variable,
                      boolean value)
```
    Sets a new boolean value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.
    
    Parameters:
    
    variable - the variable name that was completed.
    
    value - the boolean value that was answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.
  - setAnswer
```
public void setAnswer(String variable,
                      List<? extends CharSequence> values)
```
    Sets a new values to a given form's field. The field whose variable matches the requested variable will be completed with the specified values. If no field could be found for the specified variable then an exception will be raised.
    The Objects contained in the List could be of any type. The String representation of them (i.e. #toString) will be actually used when sending the answer to the server.
    
    Parameters:
    
    variable - the variable that was completed.
    
    values - the values that were answered.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable.
  - setDefaultAnswer
```
public void setDefaultAnswer(String variable)
```
    Sets the default value as the value of a given form's field. The field whose variable matches the requested variable will be completed with its default value. If no field could be found for the specified variable then an exception will be raised.
    
    Parameters:
    
    variable - the variable to complete with its default value.
    
    Throws:
    
    IllegalStateException - if the form is not of type "submit".
    
    IllegalArgumentException - if the form does not include the specified variable.
  - getFields
```
public List<FormField> getFields()
```
    Returns a List of the fields that are part of the form.
    
    Returns:
    
    a List of the fields that are part of the form.
  - getField
```
public FormField getField(String variable)
```
    Returns the field of the form whose variable matches the specified variable. The fields of type FIXED will never be returned since they do not specify a variable.
    
    Parameters:
    
    variable - the variable to look for in the form fields.
    
    Returns:
    
    the field of the form whose variable matches the specified variable.
  - hasField
```
public boolean hasField(String variable)
```
    Check if a field with the given variable exists.
    
    Parameters:
    
    variable - the variable to check for.
    
    Returns:
    
    true if a field with the variable exists, false otherwise.
    
    Since:
    
    4.2
  - getInstructions
```
public String getInstructions()
```
    Returns the instructions that explain how to fill out the form and what the form is about.
    
    Returns:
    
    instructions that explain how to fill out the form.
  - getTitle
```
public String getTitle()
```
    Returns the description of the data. It is similar to the title on a web page or an X window. You can put a title on either a form to fill out, or a set of data results.
    
    Returns:
    
    description of the data.
  - getType
```
public DataForm.Type getType()
```
    Returns the meaning of the data within the context. The data could be part of a form to fill out, a form submission or data results.
    
    Returns:
    
    the form's type.
  - setInstructions
```
public void setInstructions(String instructions)
```
    Sets instructions that explain how to fill out the form and what the form is about.
    
    Parameters:
    
    instructions - instructions that explain how to fill out the form.
  - setTitle
```
public void setTitle(String title)
```
    Sets the description of the data. It is similar to the title on a web page or an X window. You can put a title on either a form to fill out, or a set of data results.
    
    Parameters:
    
    title - description of the data.
  - getDataFormToSend
```
public DataForm getDataFormToSend()
```
    Returns a DataForm that serves to send this Form to the server. If the form is of type submit, it may contain fields with no value. These fields will be removed since they only exist to assist the user while editing/completing the form in a UI.
    
    Returns:
    
    the wrapped DataForm.
  - createAnswerForm
```
public Form createAnswerForm()
```
    Returns a new Form to submit the completed values. The new Form will include all the fields of the original form except for the fields of type FIXED. Only the HIDDEN fields will include the same value of the original form. The other fields of the new form MUST be completed. If a field remains with no answer when sending the completed form, then it won't be included as part of the completed form.
    The reason why the fields with variables are included in the new form is to provide a model for binding with any UI. This means that the UIs will use the original form (of type "form") to learn how to render the form, but the UIs will bind the fields to the form of type submit.
    
    Returns:
    
    a Form to submit the completed values.

Class Form

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Form

Form

Method Detail

getFormFrom

addField

setAnswer

setAnswer

setAnswer

setAnswer

setAnswer

setAnswer

setAnswer

setDefaultAnswer

getFields

getField

hasField

getInstructions

getTitle

getType

setInstructions

setTitle

getDataFormToSend

createAnswerForm