Is used to write to the XML document and save it. More...
Public Functions | |
QXmlPut (const QString &rootTag) | |
QXmlPut (const QString &rootTag, const QString &xmlVersion, const QString &encoding, bool standalone, const QString &docType=QString(), const QString &publicId=QString(), const QString &systemId=QString()) | |
QXmlPut (const QXmlGet &xmlGet) | |
QDomDocument | document () const |
void | putComment (const QString &comment) |
void | putSingleTag (const QString &tagName) |
void | putString (const QString &tagName, const QString &value, bool asCDATA=false) |
void | putStringList (const QString &tagName, const QStringList &values, bool asCDATA=false) |
void | putInt (const QString &tagName, int value) |
void | putIntVector (const QString &tagName, const QVector< int > &values) |
void | putDouble (const QString &tagName, double value, char format='g', int precision=15) |
void | putDoubleVector (const QString &tagName, const QVector< double > &values, char format='g', int precision=15) |
void | putBool (const QString &tagName, bool value, QXmlPutGet::BoolFormat format=QXmlPutGet::bfYesNo) |
void | putBoolVector (const QString &tagName, const QVector< bool > &values, QXmlPutGet::BoolFormat format=QXmlPutGet::bfYesNo) |
void | putColor (const QString &tagName, const QColor &value) |
void | putSize (const QString &tagName, const QSize &value) |
void | putSizeF (const QString &tagName, const QSizeF &value) |
void | putPoint (const QString &tagName, const QPoint &value) |
void | putPointF (const QString &tagName, const QPointF &value) |
void | putRect (const QString &tagName, const QRect &value) |
void | putRectF (const QString &tagName, const QRectF &value) |
void | putDate (const QString &tagName, const QDate &value) |
void | putTime (const QString &tagName, const QTime &value) |
void | putDateTime (const QString &tagName, const QDateTime &value) |
void | putByteArray (const QString &tagName, const QByteArray &value, int blockWidth=2048, int compression=9) |
void | putImage (const QString &tagName, const QImage &value, const QString format=QString("PNG"), int blockWidth=2048) |
void | putPen (const QString &tagName, const QPen &value) |
void | putBrush (const QString &tagName, const QBrush &value) |
void | putFont (const QString &tagName, const QFont &value) |
bool | saveWidget (const QWidget *value, bool warnWhenUnsupported=true) |
int | saveWidgetsRecursive (const QWidget *parent, const QString &prefix="", const QString &suffix="", const QSet< const QWidget *> &exclude=QSet< const QWidget *>()) |
bool | saveLineEdit (const QLineEdit *value) |
bool | saveAbstractButton (const QAbstractButton *value) |
bool | saveTextEdit (const QTextEdit *value) |
bool | savePlainTextEdit (const QPlainTextEdit *value) |
bool | saveSpinBox (const QSpinBox *value) |
bool | saveDoubleSpinBox (const QDoubleSpinBox *value) |
bool | saveComboBox (const QComboBox *value, bool items) |
bool | saveAbstractSlider (const QAbstractSlider *value) |
bool | saveDateTimeEdit (const QDateTimeEdit *value) |
bool | saveFontComboBox (const QFontComboBox *value) |
bool | saveGroupBox (const QGroupBox *value) |
QXmlPut | restricted () |
void | descend (const QString &tagName) |
QXmlPut | descended (const QString &tagName) |
bool | rise () |
bool | goTo (QDomElement parentElement) |
QDomElement | element () const |
void | setAttributeString (const QString &name, const QString &value) |
void | setAttributeInt (const QString &name, int value) |
void | setAttributeIntVector (const QString &name, const QVector< int > &value) |
void | setAttributeDouble (const QString &name, double value, char format='g', int precision=15) |
void | setAttributeDoubleVector (const QString &name, const QVector< double > &value, char format='g', int precision=15) |
void | setAttributeBool (const QString &name, bool value, QXmlPutGet::BoolFormat format=QXmlPutGet::bfYesNo) |
void | setAttributeBoolVector (const QString &name, const QVector< bool > &value, QXmlPutGet::BoolFormat format=QXmlPutGet::bfYesNo) |
void | setAttributeColor (const QString &name, const QColor &value) |
QString | toString (int spacesPerIndent=2) const |
bool | save (const QString &fileName, int spacesPerIndent=2) const |
Is used to write to the XML document and save it.
QXmlPut::QXmlPut | ( | const QString & | rootTag | ) |
Creates a new XML document with a root tag named rootTag. XML version is set to 1.0, encoding to UTF-8 and standalone to false.
QXmlPut::QXmlPut | ( | const QString & | rootTag, |
const QString & | xmlVersion, | ||
const QString & | encoding, | ||
bool | standalone, | ||
const QString & | docType = QString() , |
||
const QString & | publicId = QString() , |
||
const QString & | systemId = QString() |
||
) |
Creates a new XML document with a root tag named rootTag. And the specified XML parameters.
example:
The call
creates the following XML document:
QXmlPut::QXmlPut | ( | const QXmlGet & | xmlGet | ) |
Returns an QXmlPut instance located at the current position. This can be used to read and write to the XML document at the same time.
|
inline |
Returns the QDomDocument this QXmlPut instance is using.
void QXmlPut::putComment | ( | const QString & | comment | ) |
Inserts a comment. Comments can't be read by QXmlGet and are meant for other humans reading the XML document in a text editor.
example output:
void QXmlPut::putSingleTag | ( | const QString & | tagName | ) |
Inserts a single tag with name tagName. As with every tag, you can attach attributes to it by subsequent calls to setAttribute(...) functions.
example output:
void QXmlPut::putString | ( | const QString & | tagName, |
const QString & | value, | ||
bool | asCDATA = false |
||
) |
Inserts a tag with name tagName which contains the string value. If the string contains many special characters like "<", ">" and linebreaks, you should consider setting asCDATA to true, so the string will be embedded in a CDATA-section which avoids escaping most of the special characters and thus makes it easier for users to read/modify the resulting XML document in a text editor.
Note that due to escaping mechanisms any content is allowed for value. Even if asCDATA is set to true and value itself contains a string like "<![CDATA[trick]]>", it will be saved in two disjoint CDATA sections, splitting the value string into "<![CDATA[trick]]" and ">", preserving the resulting XML validity aswell as the saved value.
example output:
void QXmlPut::putStringList | ( | const QString & | tagName, |
const QStringList & | values, | ||
bool | asCDATA = false |
||
) |
Inserts a tag with name tagName which contains the string list values. If the strings contain many special characters like "<", ">" and linebreaks, you should consider setting asCDATA to true, so the strings will be embedded in a CDATA-section which avoids escaping most of the special characters and thus makes it easier for users to read/modify the resulting XML document in a text editor.
example output:
void QXmlPut::putInt | ( | const QString & | tagName, |
int | value | ||
) |
Inserts a tag with name tagName which contains the integer value.
example output:
void QXmlPut::putIntVector | ( | const QString & | tagName, |
const QVector< int > & | values | ||
) |
Inserts a tag with name tagName which contains the integer vector value.
example output:
void QXmlPut::putDouble | ( | const QString & | tagName, |
double | value, | ||
char | format = 'g' , |
||
int | precision = 15 |
||
) |
Inserts a tag with name tagName which contains the double value.
example output:
void QXmlPut::putDoubleVector | ( | const QString & | tagName, |
const QVector< double > & | values, | ||
char | format = 'g' , |
||
int | precision = 15 |
||
) |
Inserts a tag with name tagName which contains the double vector value.
example output:
void QXmlPut::putBool | ( | const QString & | tagName, |
bool | value, | ||
QXmlPutGet::BoolFormat | format = QXmlPutGet::bfYesNo |
||
) |
Inserts a tag with name tagName which contains the bool value.
Depending on the specified format (see QXmlPutGet::BoolFormat), the boolean value is represented with different strings.
example output:
void QXmlPut::putBoolVector | ( | const QString & | tagName, |
const QVector< bool > & | values, | ||
QXmlPutGet::BoolFormat | format = QXmlPutGet::bfYesNo |
||
) |
Inserts a tag with name tagName which contains the bool vector value.
Depending on the specified format (see QXmlPutGet::BoolFormat), the boolean values are represented with different strings.
example output:
void QXmlPut::putColor | ( | const QString & | tagName, |
const QColor & | value | ||
) |
Inserts a tag with name tagName which contains the QColor value.
If the color contains no transparency component (i.e. alpha is 255), the color is saved in the format "#rrggbb". If it contains alpha, it is saved as "#rrggbbaa".
example output:
void QXmlPut::putSize | ( | const QString & | tagName, |
const QSize & | value | ||
) |
Inserts a tag with name tagName which contains the QSize value.
example output:
void QXmlPut::putSizeF | ( | const QString & | tagName, |
const QSizeF & | value | ||
) |
Inserts a tag with name tagName which contains the QSizeF value.
example output:
void QXmlPut::putPoint | ( | const QString & | tagName, |
const QPoint & | value | ||
) |
Inserts a tag with name tagName which contains the QPoint value.
example output:
void QXmlPut::putPointF | ( | const QString & | tagName, |
const QPointF & | value | ||
) |
Inserts a tag with name tagName which contains the QPointF value.
example output:
void QXmlPut::putRect | ( | const QString & | tagName, |
const QRect & | value | ||
) |
Inserts a tag with name tagName which contains the QRect value.
example output:
void QXmlPut::putRectF | ( | const QString & | tagName, |
const QRectF & | value | ||
) |
Inserts a tag with name tagName which contains the QRectF value.
example output:
void QXmlPut::putDate | ( | const QString & | tagName, |
const QDate & | value | ||
) |
Inserts a tag with name tagName which contains the QDate value.
example output:
void QXmlPut::putTime | ( | const QString & | tagName, |
const QTime & | value | ||
) |
Inserts a tag with name tagName which contains the QTime value.
example output:
void QXmlPut::putDateTime | ( | const QString & | tagName, |
const QDateTime & | value | ||
) |
void QXmlPut::putByteArray | ( | const QString & | tagName, |
const QByteArray & | value, | ||
int | blockWidth = 2048 , |
||
int | compression = 9 |
||
) |
Inserts a tag with name tagName which contains the QByteArray value.
The data of the QByteArray is saved in base-64. By setting compression to a number between 0 and 9, the data may be saved uncompressed to highly compressed. To improve handling with text editors, every blockWidth characters, a linebreak is inserted into the XML output.
example output:
void QXmlPut::putImage | ( | const QString & | tagName, |
const QImage & | value, | ||
const QString | format = QString("PNG") , |
||
int | blockWidth = 2048 |
||
) |
Inserts a tag with name tagName which contains the QImage value.
The data of the QImage is saved in base-64. Compression is determined depending on the format, "JPEG" and "JPG" are saved uncompressed (because they are compressed already), all others are compressed. To improve handling with text editors, every blockWidth characters, a linebreak is inserted into the XML output.
Available formats typically are: BMP, GIF, JPG, JPEG, PNG, PBM, PGM, PPM, TIFF, XBM, XPM. (see QImageReader::supportedImageFormats())
example output:
void QXmlPut::putPen | ( | const QString & | tagName, |
const QPen & | value | ||
) |
void QXmlPut::putBrush | ( | const QString & | tagName, |
const QBrush & | value | ||
) |
void QXmlPut::putFont | ( | const QString & | tagName, |
const QFont & | value | ||
) |
bool QXmlPut::saveWidget | ( | const QWidget * | value, |
bool | warnWhenUnsupported = true |
||
) |
Saves the state of the passed widget w inside the current parent xml tag. The xml data can later be loaded via the QXmlGet::loadWidget method, or any of the specialized widget loading methods such as QXmlGet::loadLineEdit or QXmlGet::loadSpinBox, etc.
If warnWhenUnsupported is set to true, a qDebug() output is issued when w is of an unsupported widget type.
Returns true if the widget was successfully saved to xml. Therefore it returns false if the widget is either unsupported or was not saved for other reasons (e.g. object name is empty).
Supported widget types are: QLineEdit, QAbstractButton (and subclasses such as QCheckBox and QRadioButton), QTextEdit, QPlainTextEdit, QSpinBox, QDoubleSpinBox, QComboBox, QAbstractSlider (and subclasses such as QScrollBar and QSlider), QDateTimeEdit (and subclasses such as QTimeEdit and QDateEdit), QFontComboBox, QGroupBox.
int QXmlPut::saveWidgetsRecursive | ( | const QWidget * | parent, |
const QString & | prefix = "" , |
||
const QString & | suffix = "" , |
||
const QSet< const QWidget *> & | exclude = QSet<const QWidget*>() |
||
) |
Saves the widget passed as parent to xml, as well as all direct and indirect child widgets that are supported by QXmlPutGet.
If prefix and/or suffix are provided, only widgets that have the according prefix and/or suffix in their object name are considered. This is useful for marking a specific subset of widgets for xml storage already during UI design. Further, any widgets specified in exclude are not considered.
Returns the number of widgets that were saved to xml.
bool QXmlPut::saveLineEdit | ( | const QLineEdit * | value | ) |
Saves the state of the passed QLineEdit w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadLineEdit method.
The line edit's text value is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveAbstractButton | ( | const QAbstractButton * | value | ) |
Saves the state of the passed QAbstractButton w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadAbstractButton method.
The button's checked state is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveTextEdit | ( | const QTextEdit * | value | ) |
Saves the state of the passed QTextEdit w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadTextEdit method.
The text edit's content is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::savePlainTextEdit | ( | const QPlainTextEdit * | value | ) |
Saves the state of the passed QPlainTextEdit w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadPlainTextEdit method.
The text edit's content is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveSpinBox | ( | const QSpinBox * | value | ) |
Saves the state of the passed QSpinBox w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadSpinBox method.
The spin box value is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveDoubleSpinBox | ( | const QDoubleSpinBox * | value | ) |
Saves the state of the passed QDoubleSpinBox w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadDoubleSpinBox method.
The spin box value is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveComboBox | ( | const QComboBox * | value, |
bool | items | ||
) |
Saves the state of the passed QComboBox w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadComboBox method.
The combo box selection state/text is saved to the xml entry. If items is set to true, the items themselves are saved to the xml entry, too. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveAbstractSlider | ( | const QAbstractSlider * | value | ) |
Saves the state of the passed QAbstractSlider w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadAbstractSlider method.
The slider value is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveDateTimeEdit | ( | const QDateTimeEdit * | value | ) |
Saves the state of the passed QDateTimeEdit w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadDateTimeEdit method.
The edit's date/time is saved to the xml entry. Note that this method can also handle subclasses QDateEdit and QTimeEdit. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveFontComboBox | ( | const QFontComboBox * | value | ) |
Saves the state of the passed QFontComboBox w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadFontComboBox method.
The font combo box selected font descriptor (usually only family, but potentially also size, weight, etc. if set) is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
bool QXmlPut::saveGroupBox | ( | const QGroupBox * | value | ) |
Saves the state of the passed QGroupBox w under a dedicated tag inside the current parent xml tag. The xml data can later be retrieved via the corresponding QXmlGet::loadGroupBox method.
The group box checked state is saved to the xml entry. Returns false if the widget couldn't be saved (because it has an empty object name).
Consider using saveWidget as a more convenient alternative, since the type of the widget is inferred automatically.
QXmlPut QXmlPut::restricted | ( | ) |
Returns a QXmlPut instance on the same Document and at the same position as this instance, but which is restricted to this hierarchy level (and the levels below). This means, the returned QXmlPut instance isn't allowed to rise above the current hierarchy level.
This is useful if you wish that subroutines can handle their own XML work without possibly interfering with the rest. By passing a restricted instance, it's guaranteed the subroutines don't accidentally write/read outside their designated XML element.
If only the subroutine needs to write to/read from a specific element, consider using descended.
example:
void QXmlPut::descend | ( | const QString & | tagName | ) |
Creates a tag with the name tagName and descends into it. Child elements can then be created.
Once the work in the lower hierarchy level is done, you can return to the previous position in the parent hierarchy level by calling rise.
If a subroutine needs to write to/read from a specific element, consider using descended instead of a descend-rise-pair.
example:
QXmlPut QXmlPut::descended | ( | const QString & | tagName | ) |
Returns a QXmlPut instance that is descended into and restricted to the current element. Child elements can then be created with the returned instance normally via putString etc.
Due to the restriction, the returned instance can't rise above its initial hierarchy level, i.e. into or above the hierarchy level of the instance this function is called on.
When descending into elements like this, there is no need to call rise (and thus no possibility to forget a rise), because the current instance isn't influenced. Whatever descending/rising the subroutine does with the returned instance can't break the callers XML handling code.
example:
bool QXmlPut::rise | ( | ) |
Rises to the previous position in the parent hierarchy level. This finishes the work in a lower hierarchy level that was started with descend earlier.
If a subroutine needs to write to/read from a specific element, consider using descended instead of a descend-rise-pair.
If this instance is restricted (see descended and restricted) and is already inside its highest allowed hierarchy level, a further attempt to rise will return false without changing the current hierarchy level, and cause a corresponding qDebug output.
example:
bool QXmlPut::goTo | ( | QDomElement | parentElement | ) |
Changes the current parent element to parentElement. It must be in the current QDomDocument already.
If this instance is restricted (see descended and restricted) and parentElement is not inside the allowed hierarchy, this function will return false without changing the current position, and cause a corresponding qDebug output.
You probably won't use this function very often, since normal, linear QXmlPutGet navigation should be done with descend, rise, descended, etc. However, it's useful for nonlinear XML navigation, where frequent jumps between different locations in the XML hierarchy need to be done.
|
inline |
Returns the current element as a QDomElement. This can be used as a jump target for goTo, or some low-level manipulation of the node with the Qt-DOM-interface.
void QXmlPut::setAttributeString | ( | const QString & | name, |
const QString & | value | ||
) |
Adds an attribute with name to the current element. The attribute will carry the string value.
example output:
void QXmlPut::setAttributeInt | ( | const QString & | name, |
int | value | ||
) |
Adds an attribute with name to the current element. The attribute will carry the int value.
example output:
void QXmlPut::setAttributeIntVector | ( | const QString & | name, |
const QVector< int > & | value | ||
) |
Adds an attribute with name to the current element. The attribute will carry the int vector value.
example output:
void QXmlPut::setAttributeDouble | ( | const QString & | name, |
double | value, | ||
char | format = 'g' , |
||
int | precision = 15 |
||
) |
Adds an attribute with name to the current element. The attribute will carry the double value.
example output:
void QXmlPut::setAttributeDoubleVector | ( | const QString & | name, |
const QVector< double > & | value, | ||
char | format = 'g' , |
||
int | precision = 15 |
||
) |
Adds an attribute with name to the current element. The attribute will carry the double vector value.
example output:
void QXmlPut::setAttributeBool | ( | const QString & | name, |
bool | value, | ||
QXmlPutGet::BoolFormat | format = QXmlPutGet::bfYesNo |
||
) |
Adds an attribute with name to the current element. The attribute will carry the bool value.
Depending on the specified format (see QXmlPutGet::BoolFormat), the boolean value is represented with different strings.
example output:
void QXmlPut::setAttributeBoolVector | ( | const QString & | name, |
const QVector< bool > & | value, | ||
QXmlPutGet::BoolFormat | format = QXmlPutGet::bfYesNo |
||
) |
Adds an attribute with name to the current element. The attribute will carry the bool vector value.
Depending on the specified format (see QXmlPutGet::BoolFormat), the boolean value is represented with different strings.
example output:
void QXmlPut::setAttributeColor | ( | const QString & | name, |
const QColor & | value | ||
) |
Adds an attribute with name to the current element. The attribute will carry the QColor value.
If the color contains no transparency component (i.e. alpha is 255), the color is saved in the format "#rrggbb". If it contains alpha, it is saved as "#rrggbbaa".
example output:
QString QXmlPut::toString | ( | int | spacesPerIndent = 2 | ) | const |
Returns the XML document as a string. Sub-elements are indented by spacesPerIndent spaces.
bool QXmlPut::save | ( | const QString & | fileName, |
int | spacesPerIndent = 2 |
||
) | const |
Saves the XML document to the file fileName. Sub-elements are indented by spacesPerIndent spaces.
The encoding (typically UTF-8) specified in the XML declaration (QXmlPut constructor) is used.
This function returns false if the file couldn't be created/written to.