DataFormField Class Reference

`#include <dataformfield.h>`

## Public Types

enum | FieldType { TypeBoolean , TypeFixed , TypeHidden , TypeJidMulti , TypeJidSingle , TypeListMulti , TypeListSingle , TypeTextMulti , TypeTextPrivate , TypeTextSingle , TypeNone , TypeInvalid }

## Public Member Functions

| DataFormField (FieldType type=TypeTextSingle)
| DataFormField (const std::string &name, const std::string &value=EmptyString, const std::string &label=EmptyString, FieldType type=TypeTextSingle)
| DataFormField (const Tag *tag)
virtual | ~DataFormField ()
const StringMultiMap & | options () const
virtual Tag * | tag () const
const std::string & | name () const
void | setName (const std::string &name)
void | setOptions (const StringMultiMap &options)
void | addOption (const std::string &label, const std::string &value)
bool | required () const
void | setRequired (bool required)
const std::string & | label () const
void | setLabel (const std::string &label)
const std::string & | description () const
void | setDescription (const std::string &desc)
const std::string & | value () const
void | setValue (const std::string &value)
const StringList & | values () const
void | setValues (const StringList &values)
void | addValue (const std::string &value)
FieldType | type () const
| operator bool () const

## Detailed Description

An abstraction of a single field in a XEP-0004 Data Form.

Author
  Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  0.7

Definition at line 33 of file dataformfield.h.

## Member Enumeration Documentation

## FieldType

enum FieldType

Describes the possible types of a Data Form Field.

Enumerator
TypeBoolean | The field enables an entity to gather or provide an either-or choice between two options. The default value is "false".
TypeFixed | The field is intended for data description (e.g., human-readable text such as "section" headers) rather than data gathering or provision. The <value/> child SHOULD NOT contain newlines (the \n and \r characters); instead an application SHOULD generate multiple fixed fields, each with one <value/> child.
TypeHidden | The field is not shown to the entity providing information, but instead is returned with the form.
TypeJidMulti | The field enables an entity to gather or provide multiple Jabber IDs.
TypeJidSingle | The field enables an entity to gather or provide a single Jabber ID.
TypeListMulti | The field enables an entity to gather or provide one or more options from among many.
TypeListSingle | The field enables an entity to gather or provide one option from among many.
TypeTextMulti | The field enables an entity to gather or provide multiple lines of text.
TypeTextPrivate | The field enables an entity to gather or provide a single line or word of text, which shall be obscured in an interface (e.g., *****).
TypeTextSingle | The field enables an entity to gather or provide a single line or word of text, which may be shown in an interface. This field type is the default and MUST be assumed if an entity receives a field type it does not understand.
TypeNone | The field is child of either a <reported> or <item> element or has no type attribute.
TypeInvalid | The field is invalid. Only possible if the field was created from a Tag not correctly describing a Data Form Field.

Definition at line 40 of file dataformfield.h.

## Constructor & Destructor Documentation

## DataFormField() [1/3]

DataFormField | ( | FieldType | type = TypeTextSingle | ) |

Constructs a new DataForm field.

Parameters

  type | The type of the field. Default: text-single.

Definition at line 26 of file dataformfield.cpp.

## DataFormField() [2/3]

DataFormField | ( | const std::string & | name,
|  | const std::string & | value = EmptyString,
|  | const std::string & | label = EmptyString,
|  | FieldType | type = TypeTextSingle )

Constructs a new DataForm field and fills it with the given values.

Parameters

  name | The field's name (the value of the 'var' attribute).
  value | The field's value.
  label | The field's label.
  type | The field's type.

Since
  0.9

Definition at line 31 of file dataformfield.cpp.

## DataFormField() [3/3]

DataFormField | ( | const Tag * | tag | ) |

Constructs a new Data Form Field from an existing tag that describes a field.

Parameters

  tag | The tag to parse.

Definition at line 38 of file dataformfield.cpp.

## ~DataFormField()

~DataFormField | ( |  | ) |

virtual

Virtual destructor.

Definition at line 84 of file dataformfield.cpp.

## Member Function Documentation

## addOption()

void addOption | ( | const std::string & | label,
|  | const std::string & | value )

inline

Adds a single option to the list of options.

Parameters

  label | The label of the option.
  value | The value of the option.

Since
  0.9.4

Definition at line 146 of file dataformfield.h.

## addValue()

void addValue | ( | const std::string & | value | ) |

inline

Adds a single value to the list of values.

Parameters

  value | The value to add.

Definition at line 214 of file dataformfield.h.

## description()

const std::string & description | ( |  | ) | const

inline

Use this function to retrieve the description of this field.

Returns
  The description of this field

Definition at line 177 of file dataformfield.h.

## label()

const std::string & label | ( |  | ) | const

inline

Use this function to retrieve the describing label of this field.

Returns
  The describing label of this field.

Definition at line 165 of file dataformfield.h.

## name()

const std::string & name | ( |  | ) | const

inline

Use this function to retrieve the name of the field (the content of the 'var' attribute).

Returns
  The name of the field.

Definition at line 122 of file dataformfield.h.

## operator bool()

operator bool | ( |  | ) | const

inline

Converts to true if the FormBase is valid, false otherwise.

Definition at line 225 of file dataformfield.h.

## options()

const StringMultiMap & options | ( |  | ) | const

inline

Use this function to retrieve the optional values of a field.

Returns
  The options of a field.

Definition at line 108 of file dataformfield.h.

## required()

bool required | ( |  | ) | const

inline

Use this function to determine whether or not this field is required.

Returns
  Whether or not this field is required.

Definition at line 153 of file dataformfield.h.

## setDescription()

void setDescription | ( | const std::string & | desc | ) |

inline

Use this function to set the description of this field.

Parameters

  desc | The description of this field.

Definition at line 183 of file dataformfield.h.

## setLabel()

void setLabel | ( | const std::string & | label | ) |

inline

Use this function to set the describing label of this field.

Parameters

  label | The describing label of this field.

Definition at line 171 of file dataformfield.h.

## setName()

void setName | ( | const std::string & | name | ) |

inline

Sets the name (the content of the 'var' attribute) of the field. The name identifies the field uniquely in the form.

Parameters

  name | The new name of the field.

Note
  Fields of type other than 'fixed' MUST have a name, if it is 'fixed', it MAY.

Definition at line 130 of file dataformfield.h.

## setOptions()

void setOptions | ( | const StringMultiMap & | options | ) |

inline

Use this function to set the optional values of the field. The key of the map will be used as the label of the option, while the value will be used as ... the value. ;)

Parameters

  options | The optional values of a list* or *multi type of field.

Definition at line 138 of file dataformfield.h.

## setRequired()

void setRequired | ( | bool | required | ) |

inline

Use this field to set this field to be required.

Parameters

  required | Whether or not this field is required.

Definition at line 159 of file dataformfield.h.

## setValue()

void setValue | ( | const std::string & | value | ) |

inline

Use this function to set the value of this field.

Parameters

  value | The new value of this field.

Definition at line 195 of file dataformfield.h.

## setValues()

void setValues | ( | const StringList & | values | ) |

inline

Use this function to set multiple values of this field, if it is of type 'text-multi'. If its not, use setValue() instead.

Parameters

  values | The new values of this field.

Definition at line 208 of file dataformfield.h.

## tag()

Tag * tag | ( |  | ) | const

virtual

Use this function to create a Tag representation of the form field. This is usually called by DataForm.

Returns
  A Tag hierarchically describing the form field, or NULL if the field is invalid (i.e. created from a Tag not correctly describing a Data Form Field).

Definition at line 88 of file dataformfield.cpp.

## type()

FieldType type | ( |  | ) | const

inline

Use this function to retrieve the type of this field.

Returns
  The type of this field.

Definition at line 220 of file dataformfield.h.

## value()

const std::string & value | ( |  | ) | const

inline

Use this function to retrieve the value of this field.

Returns
  The value of this field.

Definition at line 189 of file dataformfield.h.

## values()

const StringList & values | ( |  | ) | const

inline

Use this function to retrieve the values of this field, if its of type 'text-multi'.

Returns
  The value of this field.

Definition at line 201 of file dataformfield.h.

The documentation for this class was generated from the following files:

- dataformfield.h
- dataformfield.cpp