KoProperty::Property Class Reference

#include <property.h>

Classes
class	ListData

Public Types
typedef TQAsciiDict< Property >	Dict
typedef TQAsciiDictIterator< Property >	DictIterator

Public Member Functions
	Property ()
	Property (const TQCString &name, const TQVariant &value=TQVariant(), const TQString &caption=TQString(), const TQString &description=TQString(), int type=Auto, Property *parent=0)
	Property (const TQCString &name, const TQStringList &keys, const TQStringList &strings, const TQVariant &value=TQVariant(), const TQString &caption=TQString(), const TQString &description=TQString(), int type=ValueFromList, Property *parent=0)
	Property (const TQCString &name, ListData *listData, const TQVariant &value=TQVariant(), const TQString &caption=TQString(), const TQString &description=TQString(), int type=ValueFromList, Property *parent=0)
	Property (const Property &prop)
TQCString	name () const
void	setName (const TQCString &name)
TQString	caption () const
TQString	captionForDisplaying () const
void	setCaption (const TQString &caption)
TQString	description () const
void	setDescription (const TQString &description)
int	type () const
void	setType (int type)
TQVariant	value () const
TQVariant	oldValue () const
void	setValue (const TQVariant &value, bool rememberOldValue=true, bool useCustomProperty=true)
void	resetValue ()
ListData *	listData () const
void	setListData (ListData *list)
void	setListData (const TQStringList &keys, const TQStringList &names)
void	setIcon (const TQString &icon)
TQString	icon () const
const TQValueList< Property * > *	children () const
Property *	child (const TQCString &name)
Property *	parent () const
CustomProperty *	customProperty () const
void	setCustomProperty (CustomProperty *prop)
bool	isNull () const
	operator bool () const
bool	isModified () const
void	clearModifiedFlag ()
bool	isReadOnly () const
void	setReadOnly (bool readOnly)
bool	isVisible () const
void	setVisible (bool visible)
bool	isStorable () const
void	setStorable (bool storable)
int	autoSync () const
void	setAutoSync (int sync)
void	setOption (const char *name, const TQVariant &val)
TQVariant	option (const char *name) const
bool	hasOptions () const
const Property &	operator= (const TQVariant &val)
const Property &	operator= (const Property &property)
bool	operator== (const Property &prop) const
int	sortingKey () const

Static Public Attributes
static const Property	null

Protected Member Functions
void	addChild (Property *prop)
void	addSet (Set *set)
void	setSortingKey (int key)
const TQValueList< Property * > *	related () const
void	addRelatedProperty (Property *property)
void	emitPropertyChanged ()
void	debug ()

Protected Attributes
PropertyPrivate *	d

Friends
class	Set
class	Buffer
class	CustomProperty

Detailed Description

The base class representing a single property.

It can hold a property of any type supported by TQVariant. You can also create you own property types (see Using Custom Properties in Factory doc). As a consequence, do not subclass Property, use CustomProperty instead.
Each property stores old value to allow undo. It has a name (a TQCString), a caption (i18n'ed name shown in Editor) and a description (also i18n'ed).
It also supports setting arbitrary number of options (of type option=value). See Editor for a list of options, and their meaning.

// To create a property
property = Property(name, value, caption, description); // name is a TQCString,
// value is whatever type TQVariant supports
 
// To create a valueFromList property (matching strings with strings)
TQStringList keys, strings;
keys << "one" << "two" << "three"; // possible values of the property
// Strings (possibly i18n-ed) shown in the editor instead of the values
strings << i18n("One") << i18n("Two") << i18n("Three");
property = Property(name, keys, strings, "two", caption);
 
// To create a valueFromList property (matching strings with TQVariant)
TQValueList<TQVariant> keys2;
keys2.append(1);
keys2.append(2);
keys2.append(3);
Property::ListData listData(keys2, strings);
m_set->addProperty(new Property("List2", listData, "otheritem", "List2"), group);

Note that you need to use TQVariant(bool, int) to create a boolean property value. See TQVariant docs for more details.

Sometimes, for longer property captions or these with more words, e.g. "Allow Zero Size", it's usable to provide newline characters, e.g. "Allow Zero\nSize". If caption argument of the constructors contains newline characters, caption() will return this text with substituted these characters with spaces. In such cases, captionForDisplaying() is used to get the original caption text usable (with newline, if any) for displaying within a property editor.

Author

Cedric Pasteur cedri.nosp@m.c.pa.nosp@m.steur.nosp@m.@fre.nosp@m.e.fr

Alexander Dymo cloud.nosp@m.temp.nosp@m.le@ms.nosp@m.kat..nosp@m.net

Jaroslaw Staniek js@ii.nosp@m.dea..nosp@m.pl

Definition at line 176 of file property.h.

Member Typedef Documentation

Dict

typedef TQAsciiDict<Property> KoProperty::Property::Dict

Definition at line 182 of file property.h.

DictIterator

typedef TQAsciiDictIterator<Property> KoProperty::Property::DictIterator

Definition at line 183 of file property.h.

Constructor & Destructor Documentation

Property() [1/5]

Property::Property

(

)

Constructs a null property.

Definition at line 230 of file property.cpp.

Property() [2/5]

Property::Property	(	const TQCString &	name,
		const TQVariant &	value = TQVariant(),
		const TQString &	caption = TQString(),
		const TQString &	description = TQString(),
		int	type = Auto,
		Property *	parent = 0
	)

Constructs property of simple type. If caption contains newline characters, caption() will return caption with substituted these with spaces. captionForDisplaying() is used to get original caption text usable (with newline, if any) for displaying within a property editor.

Definition at line 173 of file property.cpp.

Property() [3/5]

Property::Property	(	const TQCString &	name,
		const TQStringList &	keys,
		const TQStringList &	strings,
		const TQVariant &	value = TQVariant(),
		const TQString &	caption = TQString(),
		const TQString &	description = TQString(),
		int	type = ValueFromList,
		Property *	parent = 0
	)

Constructs property of ValueFromList type.

Definition at line 194 of file property.cpp.

Property() [4/5]

Property::Property	(	const TQCString &	name,
		ListData *	listData,
		const TQVariant &	value = TQVariant(),
		const TQString &	caption = TQString(),
		const TQString &	description = TQString(),
		int	type = ValueFromList,
		Property *	parent = 0
	)

Constructs property of ValueFromList type. This is overload of the above ctor added for convenience.

Definition at line 212 of file property.cpp.

Property() [5/5]

Property::Property

(

const Property &

prop

)

Constructs a deep copy of prop property.

Definition at line 235 of file property.cpp.

~Property()

Property::~Property

(

)

Definition at line 241 of file property.cpp.

Member Function Documentation

addChild()

void Property::addChild ( Property *  prop )

protected

Adds prop as a child of this property. The children will be owned by this property.

Definition at line 657 of file property.cpp.

addRelatedProperty()

void Property::addRelatedProperty ( Property *  property )

protected

Adds related property for this property.

Definition at line 710 of file property.cpp.

addSet()

void Property::addSet ( Set *  set )

protected

Adds set to this property.

Definition at line 677 of file property.cpp.

autoSync()

int Property::autoSync

(

)

const

Returns

1 if the property should be synced automatically in Property Editor as soon as editor contents change (e.g. when the user types text). If autoSync() == 0, property value will be updated when the user presses Enter or when another editor gets the focus. Property follows Property Editor's global rule if autoSync() !=0 and !=1 (the default).

Definition at line 500 of file property.cpp.

caption()

TQString Property::caption

(

)

const

Returns

the caption of the property.

Definition at line 260 of file property.cpp.

captionForDisplaying()

TQString Property::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 266 of file property.cpp.

child()

Property * Property::child

(

const TQCString &

name

)

Returns

a child property for name, or NULL if there is no property with that name.

Definition at line 640 of file property.cpp.

children()

const TQValueList< Property * > * Property::children

(

)

const

Returns

a list of all children for this property, or NULL of there is no children for this property

Definition at line 634 of file property.cpp.

clearModifiedFlag()

void Property::clearModifiedFlag

(

)

Clears "modified" flag, so isModified() will return false.

Definition at line 470 of file property.cpp.

customProperty()

CustomProperty * Property::customProperty

(

)

const

Returns

the custom property for this property.or NULL if there was no custom property defined.

Definition at line 721 of file property.cpp.

debug()

void Property::debug ( )

protected

Outputs debug string for this property.

Definition at line 767 of file property.cpp.

description()

TQString Property::description

(

)

const

Returns

the description of the property.

Definition at line 278 of file property.cpp.

emitPropertyChanged()

void Property::emitPropertyChanged ( )

protected

This method emits the Set::propertyChanged() signal for all sets this property is registered in. The value() method above calls this method of the value changed.

Definition at line 742 of file property.cpp.

hasOptions()

bool Property::hasOptions

(

)

const

Returns

true if at least one option is defined for this property.

Definition at line 538 of file property.cpp.

icon()

TQString Property::icon

(

)

const

Returns

property icon's string. Can be empty.

Definition at line 302 of file property.cpp.

isModified()

bool Property::isModified

(

)

const

Returns

true if this property value is changed.

Definition at line 464 of file property.cpp.

isNull()

bool Property::isNull

(

)

const

Returns

true if this property is null. Null properties have empty names.

Definition at line 458 of file property.cpp.

isReadOnly()

bool Property::isReadOnly

(

)

const

Returns

true if the property is read-only. The property can be read-write but still not editable because the property set containing it may be set to read-only. By default the property is read-write. See Set::isReadOnly() for more details.

Definition at line 476 of file property.cpp.

isStorable()

bool Property::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 512 of file property.cpp.

isVisible()

bool Property::isVisible

(

)

const

Returns

true if the property is visible.

Definition at line 488 of file property.cpp.

listData()

Property::ListData * Property::listData

(

)

const

Returns

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

Definition at line 428 of file property.cpp.

name()

TQCString Property::name

(

)

const

Returns

the internal name of the property (that's used in List).

Definition at line 248 of file property.cpp.

oldValue()

TQVariant Property::oldValue

(

)

const

Gets the previous property value.

Definition at line 322 of file property.cpp.

operator bool()

Property::operator bool

(

)

const

Equivalent to !isNull()

Definition at line 545 of file property.cpp.

operator=() [1/2]

const Property & Property::operator=

(

const Property &

property

)

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

Definition at line 558 of file property.cpp.

operator=() [2/2]

const Property & Property::operator=

(

const TQVariant &

val

)

Equivalent to setValue(const TQVariant &)

Definition at line 551 of file property.cpp.

operator==()

bool Property::operator==

(

const Property &

prop

)

const

Compares two properties.

Definition at line 626 of file property.cpp.

option()

TQVariant Property::option

(

const char *

name

)

const

Returns

a value for option name or null value if there is no such option set.

Definition at line 530 of file property.cpp.

parent()

Property * Property::parent

(

)

const

Returns

parent property for this property, or NULL if there is no parent property.

Definition at line 651 of file property.cpp.

related()

const TQValueList< Property * > * Property::related ( ) const

protected

Returns

a list of related properties for this property.

Definition at line 704 of file property.cpp.

resetValue()

void Property::resetValue

(

)

Resets the value of the property to the old value.

See also

oldValue()

Definition at line 401 of file property.cpp.

setAutoSync()

void Property::setAutoSync

(

int

sync

)

if sync is 1, the property will be synced automatically in the Property Editor as soon as editor's contents change (e.g. when the user types text). If sync is 0, property value will be updated when the user presses Enter or when another editor gets the focus. Property follows Property Editor's global rule if sync !=0 and !=1 (the default).

Definition at line 506 of file property.cpp.

setCaption()

void Property::setCaption

(

const TQString &

caption

)

Sets the name of the property. If the caption contains newline characters, these are replaced by spaces. You can use captionForDisplaying() to access the original caption text you passed here.

Definition at line 272 of file property.cpp.

setCustomProperty()

void Property::setCustomProperty

(

CustomProperty *

prop

)

Sets custom property prop for this property.

See also

CustomPropertyFactory

Definition at line 727 of file property.cpp.

setDescription()

void Property::setDescription

(

const TQString &

description

)

Sets the description of the property.

Definition at line 284 of file property.cpp.

setIcon()

void Property::setIcon

(

const TQString &

icon

)

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

Definition at line 308 of file property.cpp.

setListData() [1/2]

void Property::setListData	(	const TQStringList &	keys,
		const TQStringList &	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 445 of file property.cpp.

setListData() [2/2]

void Property::setListData

(

ListData *

list

)

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

Definition at line 434 of file property.cpp.

setName()

void Property::setName

(

const TQCString &

name

)

Sets the internal name of the property.

Definition at line 254 of file property.cpp.

setOption()

void Property::setOption	(	const char *	name,
		const TQVariant &	val
	)

Sets value val for option name. Options are used to describe additional details for property behaviour, e.g. within Editor. See Editor ctor documentation for the list of supported options.

Definition at line 524 of file property.cpp.

setReadOnly()

void Property::setReadOnly

(

bool

readOnly

)

Sets this property to be read-only.

See also

isReadOnly()

Definition at line 482 of file property.cpp.

setSortingKey()

void Property::setSortingKey ( int  key )

protected

Sets a key used for sorting.

Definition at line 737 of file property.cpp.

setStorable()

void Property::setStorable

(

bool

storable

)

Sets "storable" flag for this property.

See also

isStorable()

Definition at line 518 of file property.cpp.

setType()

void Property::setType

(

int

type

)

Sets the type of the property.

Definition at line 296 of file property.cpp.

setValue()

void Property::setValue	(	const TQVariant &	value,
		bool	rememberOldValue = true,
		bool	useCustomProperty = true
	)

Sets the value of the property.

Definition at line 331 of file property.cpp.

setVisible()

void Property::setVisible

(

bool

visible

)

Set the visibility.

Definition at line 494 of file property.cpp.

sortingKey()

int Property::sortingKey

(

)

const

Returns

a key used for sorting. Usually it's set by Set::addProperty() and Property::addChild() t oa unique value, so that this property can be sorted in a property editor in original order.

See also

EditorItem::compare()

Definition at line 732 of file property.cpp.

type()

int Property::type

(

)

const

Returns

the type of the property.

Definition at line 290 of file property.cpp.

value()

TQVariant Property::value

(

)

const

Returns

the value of the property.

Definition at line 314 of file property.cpp.

Friends And Related Symbol Documentation

Buffer

friend class Buffer

friend

Definition at line 437 of file property.h.

CustomProperty

friend class CustomProperty

friend

Definition at line 438 of file property.h.

Set

friend class Set

friend

Definition at line 436 of file property.h.

Member Data Documentation

d

PropertyPrivate* KoProperty::Property::d

protected

Definition at line 434 of file property.h.

null

const Property KoProperty::Property::null

static

A contant for null property.

Definition at line 180 of file property.h.

---

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

• property.h
• property.cpp