Item Class Reference

#include <Item.hpp>

Inheritance diagram for Item:

Public Member Functions
	Item (const Item &)=delete
virtual	~Item ()
void	addChild (Item *child)
const vector< Item * > &	children () const
virtual void	clearItemListProperty (const PropertyDef *property)
void	destroyChild (Item *child)
virtual bool	getBoolProperty (const PropertyDef *property) const
virtual vector< double >	getDoubleListProperty (const PropertyDef *property) const
virtual double	getDoubleProperty (const PropertyDef *property) const
virtual string	getEnumProperty (const PropertyDef *property) const
virtual int	getIntProperty (const PropertyDef *property) const
virtual vector< Item * >	getItemListProperty (const PropertyDef *property) const
virtual Item *	getItemProperty (const PropertyDef *property) const
virtual string	getStringProperty (const PropertyDef *property) const
int	getUtilityProperty (string name) const
virtual void	insertIntoItemListProperty (const PropertyDef *property, int index, Item *item)
Item &	operator= (const Item &)=delete
Item *	parent () const
virtual void	removeFromItemListProperty (const PropertyDef *property, int index)
virtual void	setBoolProperty (const PropertyDef *property, bool value)
virtual void	setDoubleListProperty (const PropertyDef *property, vector< double > value)
virtual void	setDoubleProperty (const PropertyDef *property, double value)
virtual void	setEnumProperty (const PropertyDef *property, string value)
virtual void	setIntProperty (const PropertyDef *property, int value)
virtual void	setItemProperty (const PropertyDef *property, Item *item)
virtual void	setStringProperty (const PropertyDef *property, string value)
void	setUtilityProperty (string name, int value)
virtual string	type () const

Protected Member Functions
	Item ()

Private Types
using	BaseType
using	ItemType

Private Member Functions
void	removeChild (Item *child)
void	setParent (Item *parent)

Private Attributes
vector< Item * >	_children
Item *	_parent
UtilityData *	_utility

Friends
class	ItemRegistry

Detailed Description

The Item class is the abstract base class for user classes corresponding to the SMILE data types listed in a SMILE schema. In other words, an instance of an Item subclass represents a particular item in a dataset described by a SMILE schema. Such an instance is therefore also called an item. An item subclass can have discoverable properties, as listed in the SMILE schema. The supported property types include scalar types such as integers and doubles, as well as property types that serve to hold one or more other items. All items corresponding to a particular SMILE dataset are linked into a run-time hierarchy in the form of a tree. The item and item list properties serve as aggregators for the item tree. Child nodes are owned by their parent node so that the root node indirectly owns all nodes in the tree.

Ghost and client items

There are two fundamentally different kinds of SMILE items and hierarchies: ghost items/hierarchies and client items/hierarchies. Both kinds reflect a SMILE data set according to the rules defined in a SMILE schema, and handle the corresponding properties and aggregation. The difference is in where and how the Item subclasses used in the hierarchy are defined.

Ghost items are instances of the GhostItem class defined as part of the SMILE library. A ghost item offers generic functionality to store its type (as a string) and to manage property values. The getters and setters expect the property name as a string. A ghost item has no built-in knowledge about the properties it should support. It instead counts on the schema definition and on the remaining SMILE library code to avoid problems. For example, asking a ghost item for the value of a property that was never set will throw a fatal error. Ghost items and hierarchies are used to represent SMILE data sets in generic tools that operate solely based on the SMILE schema definition, such as a general SMILE data set editor or wizard.

Client items are instances of Item subclasses defined in client code that uses the SMILE library. These classes define SMILE properties through the macros provided for that purpose in the ItemInfo.hpp header file, and implement additional functionality that uses the values of these properties in some application-specific way. The SMILE library offers capabilities to generate a SMILE schema definition from a C++ class inheritance hierarchy of client Item subclasses, using the metadata generated by the ItemInfo.hpp macros. This schema definition can then be used to resurrect a hierarchy of client items and property values corresponding to the contents of a given SMILE data set. Alternatively, the schema definition can be saved to an XML representation for use in a generic SMILE tool as described above.

To limit the amount of source code that depends on the distinction between ghost and client items/hierarchies, instances of Item subclasses are usually constructed by calling the SchemaDef::createItem() function. Depending on how the SMILE schema definition was originally constructed, this function will construct a ghost item or a client item. Specifically, if the SchemaDef instance was derived from a class hierarchy of Item subclasses, a client item will be constructed. If the SchemaDef instance was loaded from an XML SMILE schema definition, a ghost item will be constructed.

Facilities in the Item base class

The Item base class offers the following facilities.

• The private and undocumented functions named "ii_..." provide the metadata ("item info") that is appropriate for this base class, and that for client Item subclasses is defined through the macros provided in ItemInfo.hpp and documented there.
• The default constructor and destructor are provided as appropriate for an abstract base class.
• The copy and move constructors and assignment operators are deleted; items can't be copied or moved because they are connected via pointers into an item hierarchy.
• The parent and child related functions allow managing the item hierarchy aggregation. These functions are called by the property setters generated by the ItemInfo.hpp macros and by the generic property setters implemented in the GhostItem class. They do not need to be invoked explicitly by client code in most situations.
• The type() function returns the name of this item's type as a string, also for client items.
• The generic property setters and getters, provided for each supported property data type, allow access to property values given a property name as a string. These functions work both for client items (implemented in this base class using the metadata generated by the the macros in the ItemInfo.hpp header) and for ghost items (implemented in the GhostItem class).
• The utility property setters and getters can be used by the program to store extra information unrelated to the SMILE schema, for example during interactive editing of a SMILE dataset. These functions are implemented in this base class and work for both client and ghost items.

Implementing client items

The C++ class definition of a client Item subclass must declare metadata for the class and for its discoverable properties through the macros provided in the ItemInfo.hpp header. Refer to the documentation in that header for more information.

Constructor & Destructor Documentation

Item() [1/2]

Item::Item ( )

inlineprotected

The constructor (declared protected because this is an abstract class) creates a new item without any children and with its parent initialized to the null pointer. For all items other than the root node, the parent is set later on by handing the item to an item or item list property of another item (which calls the addChild() function, which in turn calls the setParent() function).

Item() [2/2]

Item::Item ( const Item & )

delete

The copy constructor is deleted. Item instances can't be copied or moved because they are connected via pointers into an item hierarchy.

~Item()

virtual Item::~Item ( )

virtual

The destructor also destroys all children of this item, recursively.

Member Function Documentation

addChild()

void Item::addChild

(

Item *

child

)

Adds the specified item to the list of children, and calls the child's setParent() function to set its parent. Setters for item or item list properties must call this function to cause the item to take ownership of items added to the property.

children()

const vector< Item * > & Item::children

(

)

const

Returns a list of the child items of this item, in arbitrary order. The list includes all items pointed to by item and item list properties. The list may be empty.

clearItemListProperty()

virtual void Item::clearItemListProperty ( const PropertyDef * property )

virtual

Sets the specified item list property to the empty list, removing any items that were present.

Reimplemented in GhostItem.

destroyChild()

void Item::destroyChild

(

Item *

child

)

Removes the specified item from the list of children, and then destroys it (and its children, recursively). Setters for item or item list properties must call this function to destroy items removed from the property.

getBoolProperty()

virtual bool Item::getBoolProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified Boolean property. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getDoubleListProperty()

virtual vector< double > Item::getDoubleListProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified floating point list property. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getDoubleProperty()

virtual double Item::getDoubleProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified floating point property. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getEnumProperty()

virtual string Item::getEnumProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified enumeration property. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getIntProperty()

virtual int Item::getIntProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified integer property. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getItemListProperty()

virtual vector< Item * > Item::getItemListProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified item list property. Ownership for the returned items is not handed over. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getItemProperty()

virtual Item * Item::getItemProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified item property. Ownership for the returned item is not handed over. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getStringProperty()

virtual string Item::getStringProperty ( const PropertyDef * property ) const

virtual

Returns the value of the specified string property. If the property does not exist, the function throws an error.

Reimplemented in GhostItem.

getUtilityProperty()

int Item::getUtilityProperty

(

string

name

)

const

Returns the value of the specified utility property. If the property does not exist, the function throws an error.

insertIntoItemListProperty()

virtual void Item::insertIntoItemListProperty ( const PropertyDef * property, int index, Item * item )

virtual

Adds the specified item to the specified item list property, and sets the parent of the specified item to the receiving item so that ownership is handed over to the receiving item. Assume that the item list property has N items when this function is called (i.e. before anything is changed). If the specified zero-based index is in the range [0,N-1], the new item is inserted at the specified index (i.e. just before the item that was there previously). If the index is out of this range (i.e. it is negative or at least N), the new item is added at the end of the list.

Reimplemented in GhostItem.

operator=()

Item & Item::operator= ( const Item & )

delete

The assignment operator is deleted. Item instances can't be copied or moved because they are connected via pointers into an item hierarchy.

parent()

Item * Item::parent

(

)

const

Returns the parent item of this item, or the null pointer if the parent has not been set.

removeChild()

void Item::removeChild ( Item * child )

private

Removes the specified item from the list of children, without destroying it. This function is called from the destructor of child items and should never be called directly.

removeFromItemListProperty()

virtual void Item::removeFromItemListProperty ( const PropertyDef * property, int index )

virtual

Removes the item at the specified index from the specified item list property and deletes it. If the index is out of range, nothing happens.

Reimplemented in GhostItem.

setBoolProperty()

virtual void Item::setBoolProperty ( const PropertyDef * property, bool value )

virtual

Sets the specified Boolean property to the specified value.

Reimplemented in GhostItem.

setDoubleListProperty()

virtual void Item::setDoubleListProperty ( const PropertyDef * property, vector< double > value )

virtual

Sets the specified floating point list property to the specified value.

Reimplemented in GhostItem.

setDoubleProperty()

virtual void Item::setDoubleProperty ( const PropertyDef * property, double value )

virtual

Sets the specified floating point property to the specified value.

Reimplemented in GhostItem.

setEnumProperty()

virtual void Item::setEnumProperty ( const PropertyDef * property, string value )

virtual

Sets the specified enumeration property to the specified value.

Reimplemented in GhostItem.

setIntProperty()

virtual void Item::setIntProperty ( const PropertyDef * property, int value )

virtual

Sets the specified integer property to the specified value.

Reimplemented in GhostItem.

setItemProperty()

virtual void Item::setItemProperty ( const PropertyDef * property, Item * item )

virtual

Sets the specified item property to the specified item, and sets the parent of the specified item to the receiving item so that ownership is handed over to the receiving item. If the specified property already holds another item, that item is destructed.

Reimplemented in GhostItem.

setParent()

void Item::setParent ( Item * parent )

private

Sets the item's parent to the specified item. This function is called from the addChild() function and should never be called directly.

setStringProperty()

virtual void Item::setStringProperty ( const PropertyDef * property, string value )

virtual

Sets the specified string property to the specified value.

Reimplemented in GhostItem.

setUtilityProperty()

void Item::setUtilityProperty	(	string	name,
		int	value )

Sets the specified utility property to the specified value. Utility properties can be used by the program to store extra information unrelated to the SMILE schema, for example during interactive editing of a SMILE dataset.

type()

virtual string Item::type ( ) const

virtual

Returns the name of the item's type.

Reimplemented in DustMixFragment, and GhostItem.

---

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

• Item.hpp