KProperty

#include <KProperty.h>

Public Types

enum  Type {
  Auto = 0x00ffffff, Invalid = QVariant::Invalid, BitArray = QVariant::BitArray, Bitmap = QVariant::Bitmap,
  Bool = QVariant::Bool, Brush = QVariant::Brush, ByteArray = QVariant::ByteArray, Char = QVariant::Char,
  Color = QVariant::Color, Cursor = QVariant::Cursor, Date = QVariant::Date, DateTime = QVariant::DateTime,
  Double = QVariant::Double, Font = QVariant::Font, Icon = QVariant::Icon, Image = QVariant::Image,
  Int = QVariant::Int, KeySequence = QVariant::KeySequence, Line = QVariant::Line, LineF = QVariant::LineF,
  List = QVariant::List, Locale = QVariant::Locale, LongLong = QVariant::LongLong, Map = QVariant::Map,
  Matrix = QVariant::Matrix, Transform = QVariant::Transform, Palette = QVariant::Palette, Pen = QVariant::Pen,
  Pixmap = QVariant::Pixmap, Point = QVariant::Point, PointF = QVariant::PointF, Polygon = QVariant::Polygon,
  Rect = QVariant::Rect, RectF = QVariant::RectF, RegExp = QVariant::RegExp, Region = QVariant::Region,
  Size = QVariant::Size, SizeF = QVariant::SizeF, SizePolicy = QVariant::SizePolicy, String = QVariant::String,
  StringList = QVariant::StringList, TextFormat = QVariant::TextFormat, TextLength = QVariant::TextLength, Time = QVariant::Time,
  UInt = QVariant::UInt, ULongLong = QVariant::ULongLong, Url = QVariant::Url, ValueFromList = 1000,
  Symbol, FontName, LineStyle, ComposedUrl,
  UserDefined = 4000
}
 
enum  ValueOption { ValueOption::None = 0, ValueOption::IgnoreOld = 1, ValueOption::IgnoreComposedProperty = 2 }
 
typedef QFlags< ValueOptionValueOptions
 
enum  ValueSyncPolicy { ValueSyncPolicy::Editor, ValueSyncPolicy::FocusOut, ValueSyncPolicy::Auto }
 

Public Member Functions

 KProperty ()
 
 KProperty (const QByteArray &name, const QVariant &value=QVariant(), const QString &caption=QString(), const QString &description=QString(), int type=Auto, KProperty *parent=nullptr)
 
 KProperty (const QByteArray &name, KPropertyListData *listData, const QVariant &value=QVariant(), const QString &caption=QString(), const QString &description=QString(), int type=ValueFromList, KProperty *parent=nullptr)
 
 KProperty (const KProperty &prop)
 
QString caption () const
 
QString captionForDisplaying () const
 
QString captionOrName () const
 
KPropertychild (const QByteArray &name)
 
const QList< KProperty * > * children () const
 
void clearModifiedFlag ()
 
KComposedPropertyInterfacecomposedProperty () const
 
QString description () const
 
bool hasOptions () const
 
QString iconName () const
 
bool isModified () const
 
bool isNull () const
 
bool isReadOnly () const
 
bool isStorable () const
 
bool isVisible () const
 
KPropertyListDatalistData () const
 
QByteArray name () const
 
QVariant oldValue () const
 
bool operator!= (const KProperty &prop) const
 
KPropertyoperator= (const QVariant &val)
 
KPropertyoperator= (const KProperty &property)
 
bool operator== (const KProperty &prop) const
 
QVariant option (const char *name, const QVariant &defaultValue=QVariant()) const
 
KPropertyparent () const
 
void resetValue ()
 
void setCaption (const QString &caption)
 
void setComposedProperty (KComposedPropertyInterface *prop)
 
void setDescription (const QString &description)
 
void setIconName (const QString &name)
 
void setListData (KPropertyListData *list)
 
void setListData (const QStringList &keys, const QStringList &names)
 
void setName (const QByteArray &name)
 
void setOption (const char *name, const QVariant &val)
 
void setReadOnly (bool readOnly)
 
void setStorable (bool storable)
 
void setType (int type)
 
bool setValue (const QVariant &value, ValueOptions options=ValueOptions())
 
void setValueSyncPolicy (ValueSyncPolicy policy)
 
void setVisible (bool visible)
 
int type () const
 
QVariant value () const
 
bool valueEqualsTo (const QVariant &value, ValueOptions valueOptions=ValueOptions()) const
 
ValueSyncPolicy valueSyncPolicy () const
 

Friends

KPROPERTYCORE_EXPORT QDebug operator<< (QDebug dbg, const KProperty &p)
 

Detailed Description

The base class representing a single property.

KProperty object can hold a property of given type supported by QVariant. Properties of custom types can be also created, see using KPropertyFactory. Composed or custom properties are not created using subclassing of KProperty but using KComposedPropertyInterface.

Each property stores old value to allows undoing that reverts the value to the old one. Property has a non-empty name (a QByteArray), a caption that is user-visible translated string displayed in property editor. Description is a translatable string that can be specified too in order to further explain meaning of the property.

Propery also supports setting arbitrary number of options using KProperty::setOption() that allow to customize look or behavior of the property in the editor.

// Creating a simple property:
// name is a QByteArray, value is whatever type QVariant supports
// Creating a property of type ValueFromList matching keys with names:
QStringList keys({"one", "two", "three"}); // possible values of the property
QStringList names({tr("One"), tr("Two"), tr("Three")}); // Names (possibly translated) shown in
// the editor instead of the keys
property = new KProperty(name, new KPropertyListData(keys, names), "two", caption);
// Creating a property of type ValueFromList matching variant keys with names:
KPropertyListData *listData = new KPropertyListData({1.1, tr("One")}, {2.5, tr("Two")}, {3., tr("Three")}});
propertySet->addProperty(new KProperty("List", listData, "otheritem", "List"));
Note
Sometimes it makes sense to split property captions that have with more words to multiple lines using a newline character, e.g. "Allow Zero Size" to "Allow Zero\nSize". This is suitable especially for the needs of property editor which can offer only limited area. The text of property caption containing newline characters is available in its original form using KProperty::captionForDisplaying(). KProperty::caption() returns modified caption text in which the newline characters are substituted with spaces and any trailing and leading whitespace is removed.

Definition at line 95 of file KProperty.h.

Member Enumeration Documentation

Defines types of properties. Properties defined by plugins should have a type number >= UserDefined .

Enumerator
ValueFromList 

string value from a list

Symbol 

unicode symbol code

FontName 

font name, e.g.

"times new roman"

LineStyle 

line style

ComposedUrl 

composed URL

Since
3.2
UserDefined 

plugin defined properties should start here

Definition at line 100 of file KProperty.h.

Options that influence how values are handled in setValue() and valueEqualsTo()

Since
3.1
Enumerator
None 

No options, that is 1.

old value is remembered before setting a new one;

  1. composed properties are considered while comparing old and new value
IgnoreOld 

Do not remember the old value before setting a new one.

IgnoreComposedProperty 

Do not use composed property when comparing values.

Definition at line 238 of file KProperty.h.

Synchronization policy for property values.

Since
3.1
Enumerator
Editor 

Allow to synchronize by the property editor using its valueSync setting (default)

FocusOut 

Synchronize the value when focus is out of the editor widget for this property or when the user presses the Enter key.

Auto 

Synchronize automatically as soon as the editor widget for this property signals (using commitData) that the value has been changed, e.g.

when the user types another letter in a text box

Definition at line 355 of file KProperty.h.

Constructor & Destructor Documentation

KProperty::KProperty ( )

Constructs a null property.

Null properties have empty names and captions and Invalid types.

Definition at line 307 of file KProperty.cpp.

KProperty::KProperty ( const QByteArray name,
const QVariant value = QVariant(),
const QString caption = QString(),
const QString description = QString(),
int  type = Auto,
KProperty parent = nullptr 
)
explicit

Constructs property of a simple type.

Definition at line 269 of file KProperty.cpp.

KProperty::KProperty ( const QByteArray name,
KPropertyListData listData,
const QVariant value = QVariant(),
const QString caption = QString(),
const QString description = QString(),
int  type = ValueFromList,
KProperty parent = nullptr 
)

Constructs property of ValueFromList type.

Ownership of listData is passed to the property object.

Definition at line 288 of file KProperty.cpp.

KProperty::KProperty ( const KProperty prop)

Constructs a deep copy of prop property.

Definition at line 312 of file KProperty.cpp.

Member Function Documentation

QString KProperty::caption ( ) const
Returns
the caption of the property. Does not contain newline characters. Can be empty.

Definition at line 336 of file KProperty.cpp.

QString KProperty::captionForDisplaying ( ) const
Returns
the caption text of the property for displaying. It is similar to caption() but if the property caption contains newline characters, these are not substituted with spaces.

Definition at line 342 of file KProperty.cpp.

QString KProperty::captionOrName ( ) const
inline
Returns
the caption of the property or name() if the caption is empty.

Definition at line 202 of file KProperty.h.

KProperty * KProperty::child ( const QByteArray name)
Returns
a child property for name, or NULL if there is no property with that name.

Definition at line 662 of file KProperty.cpp.

const QList< KProperty * > * KProperty::children ( ) const
Returns
a list of all children for this property, or NULL of there is no children for this property

Definition at line 656 of file KProperty.cpp.

void KProperty::clearModifiedFlag ( )

Clears the "modified" flag for this property and all its child properties.

After calling this method isModified() returs false for the property and all child properties.

See also
isModified()

Definition at line 497 of file KProperty.cpp.

KComposedPropertyInterface * KProperty::composedProperty ( ) const
Returns
the composed property for this property, or NULL if there was no composed property defined.

Definition at line 678 of file KProperty.cpp.

QString KProperty::description ( ) const
Returns
the description of the property.

Definition at line 354 of file KProperty.cpp.

bool KProperty::hasOptions ( ) const

Returns true if at least one option is specified for this property If there are no options defined true can be still returned if parent property is present and it has at least one option specified. Looking at parent property is available since 3.1.

Note
The lookup is performed recursively, first in parent, then grand parent, etc.

Definition at line 570 of file KProperty.cpp.

QString KProperty::iconName ( ) const
Returns
property icon's name. Can be empty.

Definition at line 382 of file KProperty.cpp.

bool KProperty::isModified ( ) const

Return true if value of this property or value of any child property is modified.

See also
clearModifiedFlag()

Definition at line 481 of file KProperty.cpp.

bool KProperty::isNull ( ) const
Returns
true if this property is null. Property is null if it has empty name.

Definition at line 475 of file KProperty.cpp.

bool KProperty::isReadOnly ( ) const
Returns
true if the property is read-only when used in a property editor. false by default. The property can be read-write but still not editable for the user if the parent property set's read-only flag is set.
See also
KPropertySet::isReadOnly()

Definition at line 508 of file KProperty.cpp.

bool KProperty::isStorable ( ) const
Returns
true if the property can be saved to a stream, xml, etc. There is a possibility to use "GUI" properties that aren't stored but used only in a GUI.

Definition at line 543 of file KProperty.cpp.

bool KProperty::isVisible ( ) const
Returns
true if the property is visible. Only visible properties are displayed by the property editor view.

Definition at line 520 of file KProperty.cpp.

KPropertyListData * KProperty::listData ( ) const
Returns
the qstring-to-value correspondence list of the property. used to create comboboxes-like property editors.

Definition at line 451 of file KProperty.cpp.

QByteArray KProperty::name ( ) const
Returns
name of the property
Note
empty name means a null property

Definition at line 324 of file KProperty.cpp.

QVariant KProperty::oldValue ( ) const

Returns the previous property value if it was set in setValue().

Definition at line 400 of file KProperty.cpp.

bool KProperty::operator!= ( const KProperty prop) const
Returns
true if the property is different from prop; otherwise returns false. Two properties are different if they have different names or types.
Since
3.1

Definition at line 648 of file KProperty.cpp.

KProperty & KProperty::operator= ( const QVariant val)

Equivalent to setValue(const QVariant &)

Definition at line 578 of file KProperty.cpp.

KProperty & KProperty::operator= ( const KProperty property)

Assigns a deep copy of all attributes of property to this property.

Definition at line 585 of file KProperty.cpp.

bool KProperty::operator== ( const KProperty prop) const
Returns
true if the property is equal to prop; otherwise returns false. Two properties are equal if they have the same name and type.
Note
All null properties are equal
Todo:
Compare properties deeper?

Definition at line 643 of file KProperty.cpp.

QVariant KProperty::option ( const char *  name,
const QVariant defaultValue = QVariant() 
) const

Returns value of given option Option is set if returned value is not null. If there is no option for name in given property and parent property is present (see parent()), parent property is checked. If the parent property offers the option, the value is returned. If it is not present there, defaultValue value is returned. Looking at parent property is available since 3.1.

Note
The lookup is performed recursively, first in parent, then grand parent, etc.
See also
setOption

Definition at line 564 of file KProperty.cpp.

KProperty * KProperty::parent ( ) const
Returns
parent property for this property, or NULL if there is no parent property.

Definition at line 673 of file KProperty.cpp.

void KProperty::resetValue ( )

Resets the value of the property to the old value.

See also
oldValue()

Definition at line 423 of file KProperty.cpp.

void KProperty::setCaption ( const QString caption)

Sets the name of the property. If the caption contains newline characters, these are substituted with spaces.

See also
captionForDisplaying

Definition at line 348 of file KProperty.cpp.

void KProperty::setComposedProperty ( KComposedPropertyInterface prop)

Sets composed property prop for this property.

Definition at line 684 of file KProperty.cpp.

void KProperty::setDescription ( const QString description)

Sets the description of the property.

Definition at line 360 of file KProperty.cpp.

void KProperty::setIconName ( const QString name)

Sets icon name to name for this property. Icons are optional and are used e.g. in property editor - displayed at the left hand.

Definition at line 388 of file KProperty.cpp.

void KProperty::setListData ( KPropertyListData list)

Sets the qstring-to-value correspondence list of the property. This is used to create comboboxes-like property editors.

Definition at line 457 of file KProperty.cpp.

void KProperty::setListData ( const QStringList keys,
const QStringList names 
)

Sets the string-to-value correspondence list of the property. This is used to create comboboxes-like property editors. This is overload of the above ctor added for convenience.

Definition at line 466 of file KProperty.cpp.

void KProperty::setName ( const QByteArray name)

Sets name of the property.

Note
empty name means a null property

Definition at line 330 of file KProperty.cpp.

void KProperty::setOption ( const char *  name,
const QVariant val 
)

Sets value val for option name. Options are used to override default settings of individual properties. They are most visible in property editor widgets. Option is set if it is not null. This means that empty string can be still a valid value. To unset given option, call setOption() with a null QVariant value.

Currently supported options are:

  • min: value describing minimum value for properties of integer, double, date, date/time and time types. Default is 0 for double and unsigned integer types, -INT_MAX for signed integer type. Defaults for date, date/time and time types are specified in documentation of QDateEdit::minimumDate, QDateTimeEdit::minimumDateTime and QTime::minimumTime, respectively. The value specified for this option is accepted if:
    • it is not larger than the value of the "max" option
    • it is not smaller than KPROPERTY_MIN_PRECISE_DOUBLE (for double type)
    • it is not smaller than -INT_MAX (for integer type)
    • it is not smaller than 0 (for unsigned integer type).
  • minValueText: user-visible translated string to be displayed in editor for integer, double, date, date/time and time types when the value is equal to the value of "min" option. The value specified for this option is accepted if min option is supported for given type and is specified.
    See also
    QAbstractSpinBox::specialValueText
  • max: value describing minimum value for properties of integer type. Default is KPROPERTY_MAX_PRECISE_DOUBLE for double type (maximum precise value) and INT_MAX for integer type. Defaults for date, date/time and time types are specified in documentation of QDateEdit::maximumDate, QDateTimeEdit::maximumDateTime and QTime::maximumTime, respectively. The value is ignored if it is smaller than the value of "min" option. The value specified for this option is accepted if:
    • it is not smaller than the value of the "min" option
    • it is not larger than KPROPERTY_MAX_PRECISE_DOUBLE (for double type)
    • it is not larger than INT_MAX (for integer and unsigned integer type).
  • precision: integer value >= 0 describing the number of decimals after the decimal point for double type. Default value is 2.
    See also
    QDoubleSpinBox::decimals
  • step: double value > 0.0 describing the size of the step that is taken when the user hits the up or down button of editor for double type. Default value is 0.01.
    See also
    QDoubleSpinBox::singleStep
  • 3State: boolean value used for boolean type; if true, the editor becomes a combobox (instead of checkable button) and accepts the third "null" state. Otherwise the boolean type only accepts true and false values, anything other, including invalid and null values, is converted to false.
  • yesName: user-visible translated string used for boolean type (both 2- and 3-state) to visually represent the "true" value. If not present, tr("Yes") is used.
  • noName: user-visible translated string used for boolean type (both 2- and 3-state) to visually represent the "false" value. If not present, tr("No") is used.
  • 3rdStateName: user-visible translated string used for boolean type (both 2- and 3-state) to visually represent the third "null" value. If not present, tr("None") is used.
  • nullName: user-visible translated string used for boolean type to display the "null" value, if and only if the property accepts two states (i.e. when "3State" option is false). If the "nullName" option is not set, null values are displayed as false.
  • extraValueAllowed: boolean value, if true the user is able to manually add extra values to a combobox.
  • fileMode: string value that describes types of objects that can be selected by the url editor:
    • "dirsOnly": only display and allow to select existing directories;
      See also
      QFileDialog::getExistingDirectoryUrl()
    • "existingFile": only allow to select one existing file for opening, i.e. confirmation of overwriting is not performed;
      See also
      QFileDialog::getOpenFileUrl()
    • Any other value: any file is supported, whether it exists or not; if the file exists, "confirmOverwrites" option is honored; this mode is the only one supporting non-file protocols such as ftp or http; to use them user has to enter them explicitly, file protocol is still the default
      See also
      QFileDialog::getSaveFileUrl()
    Note
    Empty URLs are always allowed.
  • confirmOverwrites: boolean value supported by the url editor; if true and the "fileMode" option is not equal to "existingFile" nor "dirsOnly" user will be asked for confirmation of file overwriting if selected file exists. false by default.
    Note
    The line edit does not validate the content.
  • multiLine: boolean value used for string type. If true, a multi-line QPlainTextEdit-based widget is used for editor; otherwise a single-line QLineEdit widget is used. false by default. Added in version 3.1.
  • prefix: string to display before the value, e.g. '$'. Supported for double and integer types and composed types based on double and integer types (Point*, Size*, Rect*).
    See also
    QDoubleSpinBox::prefix QSpinBox::prefix
  • suffix: string to display after the value, e.g. unit such as 'mm'. Supported for double and integer types and composed types based on double and integer types (Point*, Size*, Rect*). Note that only display is affected, value is not converted to any unit.
    See also
    QDoubleSpinBox::suffix QSpinBox::suffix

Definition at line 555 of file KProperty.cpp.

void KProperty::setReadOnly ( bool  readOnly)

Sets this property to be read-only.

See also
isReadOnly()

Definition at line 514 of file KProperty.cpp.

void KProperty::setStorable ( bool  storable)

Sets "storable" flag for this property.

See also
isStorable()

Definition at line 549 of file KProperty.cpp.

void KProperty::setType ( int  type)

Sets the type of the property.

Definition at line 372 of file KProperty.cpp.

bool KProperty::setValue ( const QVariant value,
ValueOptions  options = ValueOptions() 
)

Sets value of the property.

Parameters
valueNew value
optionsOptions for the value setting.
Returns
true if the value has been changed and false if the value was the same as previous one so it was not changed of if this property is null.

Definition at line 405 of file KProperty.cpp.

void KProperty::setValueSyncPolicy ( KProperty::ValueSyncPolicy  policy)

Sets synchronization policy for property values of this property See ValueSyncPolicy for details.

Since
3.1

Definition at line 537 of file KProperty.cpp.

void KProperty::setVisible ( bool  visible)

Sets the visibility flag.

Definition at line 526 of file KProperty.cpp.

int KProperty::type ( ) const
Returns
the type of the property.

Definition at line 366 of file KProperty.cpp.

QVariant KProperty::value ( ) const
Returns
the value of the property.

Definition at line 394 of file KProperty.cpp.

bool KProperty::valueEqualsTo ( const QVariant value,
ValueOptions  valueOptions = ValueOptions() 
) const
Returns
true if value of this property is equal to specified value

Takes type into account.

Parameters
valueValue to compare.
valueOptionsOptions to use when comparing. Only the None and IgnoreComposedProperties are supported.
Since
3.1

Definition at line 417 of file KProperty.cpp.

KProperty::ValueSyncPolicy KProperty::valueSyncPolicy ( ) const
Returns
synchronization policy for property values of this property
Since
3.1

Definition at line 531 of file KProperty.cpp.

Friends And Related Function Documentation

KPROPERTYCORE_EXPORT QDebug operator<< ( QDebug  dbg,
const KProperty p 
)
friend

qDebug() stream operator. Writes property p to the debug output in a nicely formatted way.

Todo:
children...

Definition at line 706 of file KProperty.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Tue Aug 11 2020 23:05:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.