libqutim  0.3.1.0
qutim_sdk_0_3::DataItem Class Reference

#include <dataforms.h>

+ Inheritance diagram for qutim_sdk_0_3::DataItem:

Public Member Functions

 DataItem ()
 
 DataItem (const QString &name, const LocalizedString &title, const QVariant &data)
 
 DataItem (const LocalizedString &title, const QVariant &data=QVariant())
 
 DataItem (const DataItem &other)
 
 ~DataItem ()
 
void addSubitem (const DataItem &subitem)
 
void allowModifySubitems (const DataItem &defaultSubitem, int maxSubitemsCount=-1)
 
QVariant data () const
 
template<typename T >
data (const T &def=T()) const
 
const char * dataChangedMethod () const
 
QObject * dataChangedReceiver () const
 
DataItem defaultSubitem () const
 
QList< QByteArray > dynamicPropertyNames () const
 
bool hasSubitems () const
 
bool isAllowedModifySubitems () const
 
bool isNull () const
 
bool isReadOnly () const
 
int maxSubitemsCount () const
 
QString name () const
 
DataItemoperator<< (const DataItem &subitem)
 
DataItemoperator= (const DataItem &other)
 
QVariant property (const char *name, const QVariant &def=QVariant()) const
 
template<typename T >
property (const char *name, const T &def=T()) const
 
bool removeSubitem (const QString &name, bool recursive=false)
 
int removeSubitems (const QString &name, bool recursive=false)
 
void setData (const QVariant &itemData)
 
void setDataChangedHandler (QObject *receiver, const char *method)
 
void setName (const QString &itemName)
 
void setProperty (const char *name, const QVariant &value)
 
void setReadOnly (bool readOnly=true)
 
void setSubitems (const QList< DataItem > &newSubitems)
 
void setTitle (const LocalizedString &itemTitle)
 
DataItem subitem (const QString &name, bool recursive=false) const
 
QList< DataItemsubitems () const
 
DataItem takeSubitem (const QString &name, bool recursive=false)
 
LocalizedString title () const
 

Detailed Description

The DataItem class specifies one field or a group of fields in a data form.

The DataItem class is part qutIM's DataForms API and describes appearance and behaviour of a group of fields in a data form if it has subitems or if allowed to modify its subitems. Otherwise, DataItem describes appearance and behaviour of one field in a data form.

A DataItem object can have name() attribute by which you can access this object later using subitem(). Use setName() to set this property.

Specifying various attributes and properties, you able to change appearance and behaviour of fields in a data form. data() is the primary attribute, defines the default field value and can be specified using setData() or in the constructors. The title() attribute specifes the field title; you can set it using setTitle(). A DataItem object also may contain dynamic properties which are manipulated using property() to read them and setProperty() to write them.

Note
If you set a property for an item, that property would be automatically set for all subitems of the item. That behaviour can be very useful when you need to define a default value for some property. For instance, if you would set read-only flag for an item, subitems of that item also would have read-only flag. Nevertheless, you can always override any property for a subitem.

The following types of data() and the dynamic properties are supported by DataForms API:

  1. QStringList (or LocalizedStringList):
    • alternatives. Holds alternative options for user and has type QStringList (or LocalizedStringList).
    • validator. Provides validation of input text and has type QValidator or QRegExp.
  2. bool.
  3. QDate.
  4. QDateTime.
  5. int:
    • minValue. Holds the minimum value. By default, this property contains 0.
    • maxValue. Holds the maximum value. By default, this property contains 100.
  6. uint:
    • minValue. Holds the minimum value. By default, this property contains 0.
    • maxValue. Holds the maximum value. By default, this property contains 100.
  7. double:
    • minValue. Holds the minimum value. By default, this property contains 0.
    • maxValue. Holds the maximum value. By default, this property contains 100.
  8. QIcon:
    • alternatives. Holds alternative options for user and has type QList<QIcon>.
    • imageSize. Holds the icon size. The default property value is QSize(32,32).
  9. QPixmap:
    • alternatives. Holds alternative options for user and has type QList<QPixmap>.
    • imageSize. Holds the pixmap size. The default property value is QSize(32,32).
  10. QImage:
    • alternatives. Holds alternative options for user and has type QList<QImage>.
    • imageSize. Holds the image size. The default property value is QSize(32,32).
  11. QString (or LocalizedString):
    • alternatives. Holds alternative options for user and has type QStringList (or LocalizedStringList).
      • editable. Holds whether the field is editable. The default property value is false.
    • validator. Provides validation of input text and has type QValidator or QRegExp.
    • password. Holds whether the input text is displayed or every character is replaced by asterisk. The default property value is false. The property can be overshadowed by the property 'alternatives'.
    • multiline. Holds whether the text is multiline. The default property value is false. The property can be overshadow by the property 'alternatives'.
    • mandatory. Holds whether the field is mandatory. The default property value is false.
      See Also
      AbstractDataForm::completeChanged()
      Another dynamic properties that are supported by DataForms API and do not depend on type of data():
  • readOnly. Holds whether the field is read only. By default, this property contains false. The property has highest priority and may overshadow other properties.
  • hideTitle. Holds whether the field title is hidden. The default property value is false.
  • titleAlternative. Holds alternative options of the title for user and has type LocalizedStringList.
  • hidden. Holds whether the field is hidden. The default property value is false.

The items that have subitems may have the following properties:

  • columns. Holds the recommended count of the columns. By default, this property contains 1. Note that on some platforms the property will be ignored (for example, on mobile telephones).
  • verticalSpacing. Holds spacing between fields that are laid out on top of each other. If no value is set, the system settings will be used.
  • horizontalSpacing. Holds spacing between fields that are laid out side by side. If no value is set, the system settings will be used.

Example of using data attribute and dynamic properties:

DataItem root("Form title");
root << DataItem("stringList", tr("StringList"), QStringList() << "string 1" << "string 2");
root << DataItem("bool", tr("Bool"), true);
root << DataItem("date", tr("Date"), QDate::currentDate());
root << DataItem("dateTime", tr("Date time"), QDateTime::currentDateTime());
root << DataItem("int", tr("Int"), 50);
root << DataItem("double", tr("Double"), 3.14);
root << DataItem("icon", tr("Icon"), Icon("qutim"));
{
Icon qutimIcon("qutim");
DataItem item("iconList", tr("Icon list"), qutimIcon);
QList<QIcon> alternatives;
alternatives << Icon("kopete") << Icon("pidgin") << qutimIcon << Icon("psi");
item.setProperty("alternatives", qVariantFromValue(alternatives));
root << item;
}
root << DataItem("image", tr("Image"), Icon(QLatin1String("qutim")).pixmap(64));
root << DataItem("string", tr("String"), "Text field");
{
DataItem item("multiline", tr("Multiline"), "Multiline");
item.setProperty("multiline", true);
root << item;
}
{
DataItem item("alternatives", tr("Alternatives"), "alternative2");
item.setProperty("alternatives", QStringList() << "alternative1" << "alternative2");
root << item;
}
{
DataItem item("alternatives", tr("Read only ... "), "field");
item.setReadOnly(true); // or item.setProperty("readOnly", true);
root << item;
}
{
DataItem item("alternatives", tr("You will not see the title"), "Field without title");
item.setProperty("hideTitle", true);
root << item;
}
{
DataItem item("alternatives", tr("Title alternative 2"), "choose title");
LocalizedStringList titleAlternatives;
titleAlternatives
<< tr("Title alternative 1")
<< tr("Title alternative 2");
item.setProperty("titleAlternatives", qVariantFromValue(titleAlternatives));
root << item;
}
QWidget *widget = DataFormsBackend::instance()->get(root);
widget->show();
dataforms_types_example.jpeg

If you want to unite several fields in a group you create a parent DataItem object and add subitems to the object using addSubitem() or setSubitems(). Example of using subitems:

DataItem root("Form title");
DataItem group("Group1");
group << DataItem("field 1", tr("Field 1"), QString());
group << DataItem("field 2", tr("Field 2"), QString());
root << group;
DataItem group2("Group2");
group2 << DataItem("field 3", tr("Field 3"), QString());
group2 << DataItem("field 4", tr("Field 4"), QString());
root << group2;
QWidget *widget = DataFormsBackend::instance()->get(root);
widget->show();
dataforms_groups_example.jpeg

It is possible to allow user to modify subitems using allowModifySubitems(). Here is an example:

DataItem root("Nicks");
DataItem defNick("Nick", QString());
defNick.setProperty("hideTitle", true);
root.allowModifySubitems(defNick, 10);
DataItem nick = defNick;
nick.setData("SokoL");
root << nick;
nick.setData("sokol");
root << nick;
QWidget *widget = DataFormsBackend::instance()->get(root);
widget->show();
dataforms_modifiable_subitems_example.jpeg

Constructor & Destructor Documentation

qutim_sdk_0_3::DataItem::DataItem ( )

Constructs a null DataItem.

See Also
isNull()
qutim_sdk_0_3::DataItem::DataItem ( const QString &  name,
const LocalizedString title,
const QVariant &  data 
)

Constructs a new DataItem with the given name, title and data attributes.

qutim_sdk_0_3::DataItem::DataItem ( const LocalizedString title,
const QVariant &  data = QVariant() 
)

Constructs a new DataItem with the given title and data attributes.

qutim_sdk_0_3::DataItem::DataItem ( const DataItem other)

Constructs a copy of other.

This operation occurs in constant time, because DataItem is implicitly shared. This makes returning a DataItem from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and this takes linear time.

See Also
operator=()
qutim_sdk_0_3::DataItem::~DataItem ( )

Destroys the DataItem.

Member Function Documentation

void qutim_sdk_0_3::DataItem::addSubitem ( const DataItem subitem)

Adds new subitem to the list of subitems of this data item.

See Also
operator<<()
void qutim_sdk_0_3::DataItem::allowModifySubitems ( const DataItem defaultSubitem,
int  maxSubitemsCount = -1 
)

Allows to modify the list of subitems by user.

Parameters
defaultSubitemThe data item that will be used for creating a new field.
maxSubitemsCountMaximum count of the subitems that user cannot exceed. -1 if there is no limits.
QVariant qutim_sdk_0_3::DataItem::data ( ) const

Returns the data of this data item.

template<typename T >
T qutim_sdk_0_3::DataItem::data ( const T &  def = T()) const

Returns the data of this data item converted to template type T.

If the data cannot be converted, def will be returned.

const char* qutim_sdk_0_3::DataItem::dataChangedMethod ( ) const

Returns the method the data signal is connected to.

QObject* qutim_sdk_0_3::DataItem::dataChangedReceiver ( ) const

Returns the receiver of the data changed signal of the field.

DataItem qutim_sdk_0_3::DataItem::defaultSubitem ( ) const

Returns the data item that will be used for creating a new field.

See Also
allowModifySubitems()
QList<QByteArray> qutim_sdk_0_3::DataItem::dynamicPropertyNames ( ) const
bool qutim_sdk_0_3::DataItem::hasSubitems ( ) const

Returns true if this data item contains at least one subitem; otherwise returns false.

bool qutim_sdk_0_3::DataItem::isAllowedModifySubitems ( ) const

Returns true if modifying of the list of subitems by user is allowed; otherwise returns false.

See Also
allowModifySubitems()
bool qutim_sdk_0_3::DataItem::isNull ( ) const

Returns true if this data item is null; otherwise return false.

bool qutim_sdk_0_3::DataItem::isReadOnly ( ) const

Returns the readOnly property.

See Also
setReadOnly()
int qutim_sdk_0_3::DataItem::maxSubitemsCount ( ) const

Returns maximum count of the subitems that user cannot exceed.

Returns -1 if there is no limits.

See Also
allowModifySubitems()
QString qutim_sdk_0_3::DataItem::name ( ) const

Returns the name of this data item.

See Also
setName()
DataItem& qutim_sdk_0_3::DataItem::operator<< ( const DataItem subitem)

Adds new subitem to the list of subitems of this data item.

See Also
addSubitem()
DataItem& qutim_sdk_0_3::DataItem::operator= ( const DataItem other)

Assigns other to this data item and returns a reference to this data item.

QVariant qutim_sdk_0_3::DataItem::property ( const char *  name,
const QVariant &  def = QVariant() 
) const

Returns the property named name.

If no such property exists, def will be returned.

See Also
setProperty()
template<typename T >
T qutim_sdk_0_3::DataItem::property ( const char *  name,
const T &  def = T() 
) const

Returns the name property converted to the template type T.

If the value cannot be converted, def will be returned.

See Also
setProperty()
bool qutim_sdk_0_3::DataItem::removeSubitem ( const QString &  name,
bool  recursive = false 
)
int qutim_sdk_0_3::DataItem::removeSubitems ( const QString &  name,
bool  recursive = false 
)
void qutim_sdk_0_3::DataItem::setData ( const QVariant &  itemData)

Sets the data of this data item to be itemData.

void qutim_sdk_0_3::DataItem::setDataChangedHandler ( QObject *  receiver,
const char *  method 
)

Connects the data changed signal of the field to the method in the receiver.

The data changed signal has three paramenters:

  • QString fieldName. The field name.
  • QVariant data. The new data of the field.
  • AbstractDataForm *dataForm. The pointer to the data form.
void qutim_sdk_0_3::DataItem::setName ( const QString &  itemName)

Sets the name of this data item to be itemName.

See Also
name()
void qutim_sdk_0_3::DataItem::setProperty ( const char *  name,
const QVariant &  value 
)

Sets name property to be value.

See Also
property()
void qutim_sdk_0_3::DataItem::setReadOnly ( bool  readOnly = true)

Sets the readOnly property to be readOnly.

See Also
isReadOnly()
void qutim_sdk_0_3::DataItem::setSubitems ( const QList< DataItem > &  newSubitems)

Sets the list of subitems to be newSubitems.

void qutim_sdk_0_3::DataItem::setTitle ( const LocalizedString itemTitle)

Sets the title of this data item to be itemTitle.

See Also
title()
DataItem qutim_sdk_0_3::DataItem::subitem ( const QString &  name,
bool  recursive = false 
) const

Returns the subitem by its name.

QList<DataItem> qutim_sdk_0_3::DataItem::subitems ( ) const

Returns the list of subitems of this data item.

See Also
setSubitems(), subitems(), addSubitem(), hasSubitems().
DataItem qutim_sdk_0_3::DataItem::takeSubitem ( const QString &  name,
bool  recursive = false 
)
LocalizedString qutim_sdk_0_3::DataItem::title ( ) const

Returns the title of this data item.

See Also
setTitle()

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

Generated by Doxygen