Detailed Description
The QOrganizerItem class is the base class of an event, todo, note, or journal entry.
A QOrganizerItem object has an id and a collection of details (like a start date and location), as well as a collection id which identifies which QOrganizerCollection the item is part of in a manager. Each detail (which can have multiple fields) is stored in an appropriate subclass of QOrganizerItemDetail, and the QOrganizerItem allows retrieving these details in various ways. QOrganizerItemExtendedDetail is supposed to be used to store user specific details that are not pre-defined in the detal leaf classes.
Most clients will want to use the convenient subclasses of QOrganizerItem (i.e., QOrganizerEvent (and QOrganizerEventOccurence), QOrganizerTodo (and QOrganizerTodoOccurence), QOrganizerJournal and QOrganizerNote) instead of manipulating instances of QOrganizerItem directly.
A QOrganizerItem instance represents the in-memory version of an organizer item. It is possible for the contents of a QOrganizerItem to change independently of the contents that are stored persistently in a QOrganizerManager. A QOrganizerItem has an id associated with it when it is first retrieved from a QOrganizerManager, or after it has been first saved, and this allows clients to track changes using the signals in QOrganizerManager. When saved in a manager, every item is placed into a QOrganizerCollection in that manager, according to the collection id set in the item prior to save (or the default collection if no collection id was set in the item).
Different QOrganizerManagers may require an item to have certain details saved in it before it can be stored in that manager. By default, every item must have a QOrganizerItemType detail which identifies the type of the item. Different subclasses of QOrganizerItem (i.e., QOrganizerEvent (and QOrganizerEventOccurence), QOrganizerTodo (and QOrganizerTodoOccurence), QOrganizerJournal and QOrganizerNote) may have other mandatory details, depending on the manager.
Member Function Documentation
QOrganizerItem::QOrganizerItem()
Construct an empty organizer item.
The organizer item will have an empty item ID, and an empty collection ID. It's of type QOrganizerItemType::TypeUndefined.
QOrganizerItem::QOrganizerItem(const QOrganizerItem & other)
Constructs an item that is a copy of other.
QOrganizerItem::~QOrganizerItem()
Frees the memory used by this item.
Adds the comment to this item
void QOrganizerItem::addTag(const QString & tag)
Adds the tag to this item.
Removes all comments of this item.
void QOrganizerItem::clearDetails()
Removes all details of the organizer item, and resets the type to be QOrganizerItemType::TypeUndefined.
void QOrganizerItem::clearTags()
Removes all tags associated with the item.
Returns the id of the collection which this item is part of, in the manager in which the item has been saved, if the item has previously been saved in a manager. If the item has not previously been saved in a manager, this function will return the id of the collection into which the client wishes the item to be saved when QOrganizerManager::saveItem() is called, which is set by calling setId(); otherwise, returns a null id.
An item always belongs to exactly one collection in a particular manager after it has been saved in the manager. If the item has previously been saved in the manager, in a particular collection, and the client sets the collection id of the item to the id of a different collection within that manager and then resaves the item, the item will be moved from its original collection into the specified collection if the move operation is supported by the manager; otherwise, the QOrganizerManager::saveItem() operation will fail and calling QOrganizerManager::error() will return QOrganizerManager::NotSupportedError.
See also setCollectionId().
Returns the list of comments of this item.
See also setComments().
QVariant QOrganizerItem::data(const QString & name) const
Returns the data of the extended detail with the given name.
See also setData().
QString QOrganizerItem::description() const
Returns the human-readable description of the item.
See also setDescription().
Returns the first detail stored in the organizer item with the given detailType. If the given detailType is TypeUndefined, it returns the first detail found.
Returns a list of details with the given detailType. If the given detailType is of TypeUndefined, it returns all the details.
QString QOrganizerItem::displayLabel() const
Returns the display label of the item.
See also setDisplayLabel().
QString QOrganizerItem::guid() const
Returns the globally unique identifier which identifies this item, which is used for synchronization purposes.
See also setGuid().
Returns the QOrganizerItemId that identifies this organizer item.
This may have been set when the organizer item was retrieved from a particular manager, or when the organizer item was first saved in a manager. The QOrganizerItemId is only valid within a specific manager. See QOrganizerManager::saveItem() for more information.
See also setId().
bool QOrganizerItem::isEmpty() const
Returns true if this QOrganizerItem is empty, false if not.
Note that the type detail of the organizer item is irrelevant.
bool QOrganizerItem::removeDetail(QOrganizerItemDetail * detail)
Removes the detail from the organizer item.
The detail in the organizer item which has the same key as that of the given detail will be removed if it exists. Only the key is used for comparison - that is, the information in the detail may be different.
Returns true if the detail was removed successfully, false if an error occurred.
Note that the caller retains ownership of the detail.
bool QOrganizerItem::saveDetail(QOrganizerItemDetail * detail)
Saves the given detail in the list of stored details, and sets the detail's id. If another detail of the same type and id has been previously saved in this organizer item, that detail is overwritten. Otherwise, a new id is generated and set in the detail, and the detail is added to the organizer item.
If detail is a QOrganizerItemType, the existing organizer item type will be overwritten with detail. There is never more than one organizer item type in a organizer item.
Returns true if the detail was saved successfully, otherwise returns false.
Note that the caller retains ownership of the detail.
void QOrganizerItem::setCollectionId(const QOrganizerCollectionId & collectionId)
Sets the id of the collection into which the client wishes the item to be saved to the given collectionId.
If the given collectionId is the null collection id, the client is specifying that the item should be saved into the collection in which the item is already saved (if the item has previously been saved in the manager, without having been removed since), or into the default collection of the manager (if the item has not previously been saved in the manager, or has been removed since the last time it was saved).
If the item has previously been saved in a particular manager, and the given collectionId is the id of a different collection than the one which the item is currently a part of in that manager, saving the item with QOrganizerManager::saveItem() will move the item from its original collection to the collection whose id is collectionId, if collectionId identifies a valid collection and the operation is supported by the manager.
See also collectionId().
Sets the list of comments associated with the item to comments.
See also comments().
void QOrganizerItem::setData(const QString & name, const QVariant & data)
Sets the data of a extended detail with the given name.
See also data().
void QOrganizerItem::setDescription(const QString & description)
Sets the human-readable description of the item to description.
See also description().
void QOrganizerItem::setDisplayLabel(const QString & label)
Sets the display label of the item to label.
See also displayLabel().
void QOrganizerItem::setGuid(const QString & guid)
Sets the item's globally unique identifier to guid.
See also guid().
void QOrganizerItem::setId(const QOrganizerItemId & id)
Sets the id of this organizer item to id.
Note that this only affects this object, not any corresponding structures stored by a QOrganizerManager.
If you change the id of a organizer item and save the organizer item in a manager, the previously existing organizer item will still exist. You can do this to create copies (possibly modified) of an existing organizer item, or to save a organizer item in a different manager.
See also id() and QOrganizerManager::saveItem().
void QOrganizerItem::setTags(const QStringList & tags)
Sets the list of tags associated with the item to tags.
See also tags().
void QOrganizerItem::setType(QOrganizerItemType::ItemType type)
Sets the type of the organizer item to the given type.
See also type().
QStringList QOrganizerItem::tags() const
Returns the list of tags for this item.
See also setTags().
QOrganizerItemType::ItemType QOrganizerItem::type() const
Returns the type of the organizer item.
See also setType().
bool QOrganizerItem::operator!=(const QOrganizerItem & other) const
Returns true if this organizer item's id or details are different to those of the other organizer item.
QOrganizerItem & QOrganizerItem::operator=(const QOrganizerItem & other)
Replace the contents of this organizer item with the other.
bool QOrganizerItem::operator==(const QOrganizerItem & other) const
Returns true if this organizer item is equal to the other organizer item, false if either the id, collection id or stored details are not the same.
