Akonadi::History Class

IncidenceChanger is the preferred way to easily create, modify and delete incidences. More...

Header: #include <history.h>
CMake: find_package(KPim6AkonadiCalendar REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::AkonadiCalendar)
Inherits: QObject

Public Types

enum ResultCode { ResultCodeSuccess, ResultCodeError }

Public Functions

virtual ~History() override
QString &lastErrorString() const
QString nextRedoDescription() const
QString nextUndoDescription() const
void recordCreation(const Akonadi::Item &item, const QString &description, const uint atomicOperationId = 0)
void recordDeletion(const Akonadi::Item &item, const QString &description, const uint atomicOperationId = 0)
void recordDeletions(const Akonadi::Item::List &items, const QString &description, const uint atomicOperationId = 0)
void recordModification(const Akonadi::Item &oldItem, const Akonadi::Item &newItem, const QString &description, const uint atomicOperationId = 0)
bool redoAvailable() const
void undoAll(QWidget *parent = nullptr)
bool undoAvailable() const

Public Slots

bool clear()
void redo(QWidget *parent = nullptr)
void undo(QWidget *parent = nullptr)

Signals

void changed()
void redone(Akonadi::History::ResultCode resultCode)
void undone(Akonadi::History::ResultCode resultCode)

Detailed Description

It hides the communication with akonadi from the library user.

It provides the following features that ItemCreateJob, ItemModifyJob and ItemDeleteJob do not: - Sending groupware ( iTip ) messages to attendees and organizers. - Aware of recurrences, allowing to only change one occurrence. - Undo/Redo - Group operations which are executed in an atomic manner. - Collection ACLs - Error dialogs with calendaring lingo

In the context of this API, "change", means "creation", "deletion" or incidence "modification".

IncidenceChanger *changer = new IncidenceChanger( parent );
connect( changer,
         SIGNAL(createFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)),
         SLOT(slotCreateFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)) );

connect( changer,
         SIGNAL(deleteFinished(int,QList<Akonadi::Item::Id>,Akonadi::IncidenceChanger::ResultCode,QString)),
         SLOT(slotDeleteFinished(int,QList<Akonadi::Item::Id>,Akonadi::IncidenceChanger::ResultCode,QString)) );

connect( changer,SIGNAL(modifyFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)),
         SLOT(slotModifyFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)) );

changer->setDestinationPolicy( IncidenceChanger::DestinationPolicyAsk );

KCalendarCore::Incidence::Ptr incidence = (...);
int changeId = changer->createIncidence( incidence, Akonadi::Collection() );


if ( changeId == -1 )
{
 // Invalid parameters, incidence is null.
}

Author: Sérgio Martins <iamsergio@gmail.com>

Member Type Documentation

enum History::ResultCode

This enum describes the possible result codes (success/error values) for an undo or redo operation.

See also undone() and redone().

Member Function Documentation

[override virtual noexcept] History::~History()

Destroys the History instance.

[signal] void History::changed()

The redo/undo stacks have changed.

[slot] bool History::clear()

Clears the undo and redo stacks. Won't do anything if there's a undo/redo job currently running.

Returns true if the stacks were cleared, false if there was a job running

QString &History::lastErrorString() const

Returns the last error message.

Call this immediately after catching the undone()/redone() signal with an ResultCode != ResultCodeSuccess.

The message is translated.

QString History::nextRedoDescription() const

Returns the description of the next redo.

This is the description that was passed when calling recordCreation(), recordDeletion() or recordModification().

See also nextUndoDescription().

QString History::nextUndoDescription() const

Returns the description of the next undo.

This is the description that was passed when calling recordCreation(), recordDeletion() or recordModification().

See also nextRedoDescription().

void History::recordCreation(const Akonadi::Item &item, const QString &description, const uint atomicOperationId = 0)

Pushes an incidence creation onto the undo stack. The creation can be undone calling undo().

item the item that was created. Must be valid and have a Incidence::Ptr payload description text that can be used in the undo/redo menu item to describe the operation If empty, a default one will be provided. atomicOperationId if not 0, specifies which group of changes this change belongs to. When a change is undone/redone, all other changes which are in the same group are also undone/redone

void History::recordDeletion(const Akonadi::Item &item, const QString &description, const uint atomicOperationId = 0)

Pushes an incidence deletion onto the undo stack. The deletion can be undone calling undo().

item The item to delete. Must be valid, doesn't need to contain a payload. description text that can be used in the undo/redo menu item to describe the operation If empty, a default one will be provided. atomicOperationId if not 0, specifies which group of changes this change belongs to. When a change is undone/redone, all other changes which are in the same group are also undone/redone

void History::recordDeletions(const Akonadi::Item::List &items, const QString &description, const uint atomicOperationId = 0)

Pushes a list of incidence deletions onto the undo stack. The deletions can be undone calling undo() once.

items The list of items to delete. All items must be valid. description text that can be used in the undo/redo menu item to describe the operation If empty, a default one will be provided. atomicOperationId If != 0, specifies which group of changes thischange belongs to. Will be useful for atomic undoing/redoing, not implemented yet.

void History::recordModification(const Akonadi::Item &oldItem, const Akonadi::Item &newItem, const QString &description, const uint atomicOperationId = 0)

Pushes an incidence modification onto the undo stack. The modification can be undone calling undo().

oldItem item containing the payload before the change. Must be valid and contain an Incidence::Ptr payload. newItem item containing the new payload. Must be valid and contain an Incidence::Ptr payload. description text that can be used in the undo/redo menu item to describe the operation If empty, a default one will be provided. atomicOperationId if not 0, specifies which group of changes this change belongs to. When a change is undone/redone, all other changes which are in the same group are also undone/redone

[slot] void History::redo(QWidget *parent = nullptr)

Reverts the change that's on top of the redo stack. Can't be called if there's an undo/redo operation running, asserts. Can be called if the stack is empty, in this case, nothing happens. This function is async, catch signal redone() to know when the operation finishes.

parent will be passed to dialogs created by IncidenceChanger, for example those asking if you want to send invitations.

See also undo() and redone().

bool History::redoAvailable() const

Returns true if there are changes that can be redone.

[signal] void History::redone(Akonadi::History::ResultCode resultCode)

This signal is emitted when an redo operation finishes. resultCode History::ResultCodeSuccess on success.

See also lastErrorString().

[slot] void History::undo(QWidget *parent = nullptr)

Reverts the change that's on top of the undo stack. Can't be called if there's an undo/redo operation running, asserts. Can be called if the stack is empty, in this case, nothing happens. This function is async, catch signal undone() to know when the operation finishes.

parent will be passed to dialogs created by IncidenceChanger, for example those asking if you want to send invitations.

See also redo() and undone().

void History::undoAll(QWidget *parent = nullptr)

Reverts every change in the undo stack.

parent will be passed to dialogs created by IncidenceChanger, for example those asking if you want to send invitations.

bool History::undoAvailable() const

Returns true if there are changes that can be undone.

[signal] void History::undone(Akonadi::History::ResultCode resultCode)

This signal is emitted when an undo operation finishes. resultCode History::ResultCodeSuccess on success.

See also lastErrorString().