KProperty Class Reference

#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 class	ValueOption { None = 0 , IgnoreOld = 1 , IgnoreComposedProperty = 2 }
typedef QFlags< ValueOption >	ValueOptions
enum class	ValueSyncPolicy { Editor , FocusOut , Auto }

Public Member Functions
	KProperty ()
	KProperty (const KProperty &prop)
	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)
QString	caption () const
QString	captionForDisplaying () const
QString	captionOrName () const
KProperty *	child (const QByteArray &name)
const QList< KProperty * > *	children () const
void	clearModifiedFlag ()
KComposedPropertyInterface *	composedProperty () 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
KPropertyListData *	listData () const
QByteArray	name () const
QVariant	oldValue () const
bool	operator!= (const KProperty &prop) const
KProperty &	operator= (const KProperty &property)
KProperty &	operator= (const QVariant &val)
bool	operator== (const KProperty &prop) const
QVariant	option (const char *name, const QVariant &defaultValue=QVariant()) const
KProperty *	parent () const
void	resetValue ()
void	setCaption (const QString &caption)
void	setComposedProperty (KComposedPropertyInterface *prop)
void	setDescription (const QString &description)
void	setIconName (const QString &name)
void	setListData (const QStringList &keys, const QStringList &names)
void	setListData (KPropertyListData *list)
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

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:
KProperty *property = new KProperty(name, value, caption, description);
// 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 Typedef Documentation

ValueOptions

typedef QFlags< ValueOption > KProperty::ValueOptions

Definition at line 244 of file KProperty.h.

Member Enumeration Documentation

Type

enum KProperty::Type

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.

ValueOption

enum class KProperty::ValueOption

strong

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; 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.

ValueSyncPolicy

enum class KProperty::ValueSyncPolicy

strong

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() [1/4]

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() [2/4]

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() [3/4]

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() [4/4]

KProperty::KProperty

(

const KProperty &

prop

)

Constructs a deep copy of prop property.

Definition at line 312 of file KProperty.cpp.

~KProperty()

KProperty::~KProperty

(

)

Definition at line 318 of file KProperty.cpp.

Member Function Documentation

caption()

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.

captionForDisplaying()

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.

captionOrName()

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.

child()

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.

children()

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.

clearModifiedFlag()

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.

composedProperty()

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.

description()

QString KProperty::description

(

)

const

Returns

the description of the property.

Definition at line 354 of file KProperty.cpp.

hasOptions()

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.

iconName()

QString KProperty::iconName

(

)

const

Returns

property icon's name. Can be empty.

Definition at line 382 of file KProperty.cpp.

isModified()

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.

isNull()

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.

isReadOnly()

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.

isStorable()

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.

isVisible()

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.

listData()

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.

name()

QByteArray KProperty::name

(

)

const

Returns

name of the property

Note

empty name means a null property

Definition at line 324 of file KProperty.cpp.

oldValue()

QVariant KProperty::oldValue

(

)

const

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

Definition at line 400 of file KProperty.cpp.

operator!=()

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.

operator=() [1/2]

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.

operator=() [2/2]

KProperty & KProperty::operator=

(

const QVariant &

val

)

Equivalent to setValue(const QVariant &)

Definition at line 578 of file KProperty.cpp.

operator==()

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.

option()

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.

parent()

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.

resetValue()

void KProperty::resetValue

(

)

Resets the value of the property to the old value.

See also

oldValue()

Definition at line 423 of file KProperty.cpp.

setCaption()

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.

setComposedProperty()

void KProperty::setComposedProperty

(

KComposedPropertyInterface *

prop

)

Sets composed property prop for this property.

Definition at line 684 of file KProperty.cpp.

setDescription()

void KProperty::setDescription

(

const QString &

description

)

Sets the description of the property.

Definition at line 360 of file KProperty.cpp.

setIconName()

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.

setListData() [1/2]

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.

setListData() [2/2]

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.

setName()

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.

setOption()

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.

setReadOnly()

void KProperty::setReadOnly

(

bool

readOnly

)

Sets this property to be read-only.

See also

isReadOnly()

Definition at line 514 of file KProperty.cpp.

setStorable()

void KProperty::setStorable

(

bool

storable

)

Sets "storable" flag for this property.

See also

isStorable()

Definition at line 549 of file KProperty.cpp.

setType()

void KProperty::setType

(

int

type

)

Sets the type of the property.

Definition at line 372 of file KProperty.cpp.

setValue()

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

Sets value of the property.

Parameters

value	New value
options	Options 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.

setValueSyncPolicy()

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.

setVisible()

void KProperty::setVisible

(

bool

visible

)

Sets the visibility flag.

Definition at line 526 of file KProperty.cpp.

type()

int KProperty::type

(

)

const

Returns

the type of the property.

Definition at line 366 of file KProperty.cpp.

value()

QVariant KProperty::value

(

)

const

Returns

the value of the property.

Definition at line 394 of file KProperty.cpp.

valueEqualsTo()

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

value	Value to compare.
valueOptions	Options to use when comparing. Only the None and IgnoreComposedProperties are supported.

Since

3.1

Definition at line 417 of file KProperty.cpp.

valueSyncPolicy()

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.

---

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

• KProperty.h
• KProperty.cpp