Undo: Track and undo or redo entity changes
[Query Object Framework]


Files

file  qofundo.h
 QOF undo handling.

Defines

#define QOF_MOD_UNDO   "qof-undo"

Functions

void qof_undo_set_param (QofEntity *ent, const QofParam *param, gchar *value)
 Set a value in this parameter of the entity.
void qof_undo_modify (QofInstance *inst, const QofParam *param)
void qof_undo_commit (QofInstance *inst, const QofParam *param)
void qof_undo_create (QofInstance *inst)
void qof_undo_delete (QofInstance *inst)
void qof_book_clear_undo (QofBook *book)
 Free the entire undo list for this book.
void qof_book_undo (QofBook *book)
 Set parameter values from before the previous event.
void qof_book_redo (QofBook *book)
 Set parameter values from after the previous event.
gboolean qof_book_can_undo (QofBook *book)
 event handler for undo widget
gboolean qof_book_can_redo (QofBook *book)
 event handler for redo widget
void qof_book_start_operation (QofBook *book, gchar *label)
 Start recording operation.
void qof_book_end_operation (QofBook *book)
 End recording the current operation.
QofTimeqof_book_undo_first_modified (QofBook *book)
 HIG compliance aid to report time of first change.
gint qof_book_undo_count (QofBook *book)
 Number of undo operations available.

Detailed Description

QOF Undo operates within a QofBook. In order to undo the changes to the entity, the initial state of each parameter is cached when an operation begins. If the entity changes are not successful, the lack of a qof_book_end_operation call before a qof_book_start_operation will cause the cached data to be freed. If the entity is changed successfully, qof_book_end_operation will create the undo data using the operation label and each of the entity changes that were successful.

Within each operation, entity changes can be recorded using QofEventHandler or individually.

Undo data consists of a list of operations that have changed data in this book and a list of entity changes for each of those operations. Each operation can relate to more than one entity change and cover more than one entity but must only relate to one book.

  1. Only QOF parameter changes can be undone or redone. Data from structs that are not QOF objects or which have no QofParam to get and set the data will not be available to the undo process.
  2. Undo relates to 'user interface operations', not engine events. This is because an operation (like an import or voiding a transaction) can involve multiple, possibly conflicting, engine events - e.g. removing an entity from one reference and inserting it as another. Therefore, the UI developer alone can decide where an operation begins and ends. All changes between the two will be undone or redone in one call to qof_book_undo.
  3. Undo operations cannot be nested. Be careful where you start and end an undo operation, if your application calls qof_book_start_operation() before calling qof_book_end_operation(), the undo cache will be freed and QofUndo will not notify you of this. The API is designed to silently handle user aborts during a user operation. As undo data is cached when editing begins, if the edit is never completed the cache must be cleared before the next operation. i.e. if the user starts to edit an entity but then cancels the operation, there are no changes to undo. It follows that any one book can only be the subject of one operation at a time.

Since:
0.7.0

Function Documentation

gboolean qof_book_can_redo ( QofBook book  ) 

event handler for redo widget

Returns:
FALSE if index_position == 0 or index_position == length otherwise TRUE.

Definition at line 422 of file qofundo.c.

00423 {
00424     QofUndo *book_undo;
00425     gint length;
00426 
00427     book_undo = book->undo_data;
00428     length = g_list_length (book_undo->undo_list);
00429     if ((book_undo->index_position == length) || (length == 0))
00430         return FALSE;
00431     return TRUE;
00432 }

gboolean qof_book_can_undo ( QofBook book  ) 

event handler for undo widget

Returns:
FALSE if length == 0 or index_position == 0, otherwise TRUE.

Definition at line 409 of file qofundo.c.

00410 {
00411     QofUndo *book_undo;
00412     gint length;
00413 
00414     book_undo = book->undo_data;
00415     length = g_list_length (book_undo->undo_list);
00416     if ((book_undo->index_position == 0) || (length == 0))
00417         return FALSE;
00418     return TRUE;
00419 }

void qof_book_clear_undo ( QofBook book  ) 

Free the entire undo list for this book.

The application needs to decide whether to reset the undo list upon session_save, application close, user intervention etc.

Definition at line 389 of file qofundo.c.

00390 {
00391     QofUndoOperation *operation;
00392     QofUndo *book_undo;
00393 
00394     if (!book)
00395         return;
00396     book_undo = book->undo_data;
00397     while (book_undo != NULL)
00398     {
00399         operation = (QofUndoOperation *) book_undo->undo_list->data;
00400         if(operation->entity_list)
00401             g_list_free (operation->entity_list);
00402         book_undo->undo_list = g_list_next (book_undo->undo_list);
00403     }
00404     book_undo->index_position = 0;
00405     g_free (book_undo->undo_label);
00406 }

void qof_book_start_operation ( QofBook book,
gchar *  label 
)

Start recording operation.

Definition at line 567 of file qofundo.c.

00568 {
00569     QofUndo *book_undo;
00570 
00571     book_undo = book->undo_data;
00572     if (book_undo->undo_operation_open && book_undo->undo_cache)
00573     {
00574         g_list_free (book_undo->undo_cache);
00575         book_undo->undo_operation_open = FALSE;
00576         if (book_undo->undo_label)
00577             g_free (book_undo->undo_label);
00578     }
00579     book_undo->undo_label = g_strdup (label);
00580     book_undo->undo_operation_open = TRUE;
00581 }

void qof_undo_commit ( QofInstance *  inst,
const QofParam param 
)

Mark this instance parameter after modification

Prepare undo data for this instance after committal. Record the modified state of this parameter of this instance so that if this operation is undone and then redone, the modification can be recreated.

Definition at line 551 of file qofundo.c.

00552 {
00553     QofUndoEntity *undo_entity;
00554     QofUndo *book_undo;
00555     QofBook *book;
00556 
00557     if (!instance || !param)
00558         return;
00559     book = instance->book;
00560     book_undo = book->undo_data;
00561     undo_entity = qof_prepare_undo (&instance->entity, param);
00562     book_undo->undo_cache =
00563         g_list_prepend (book_undo->undo_cache, undo_entity);
00564 }

void qof_undo_create ( QofInstance *  inst  ) 

prepare undo data for a new instance.

Record the creation of a new (empty) instance so that undo can delete it (and recreate it on redo).

Can be used within a QofEventHandler in response to QOF_EVENT_CREATE.

Definition at line 466 of file qofundo.c.

00467 {
00468     QofUndoEntity *undo_entity;
00469     QofBook *book;
00470     QofUndo *book_undo;
00471 
00472     if (!instance)
00473         return;
00474     book = instance->book;
00475     book_undo = book->undo_data;
00476     undo_entity = g_new0 (QofUndoEntity, 1);
00477     // to undo a create, use a delete.
00478     undo_entity->how = UNDO_DELETE;
00479     undo_entity->guid = qof_instance_get_guid (instance);
00480     undo_entity->type = instance->entity.e_type;
00481     book_undo->undo_cache =
00482         g_list_prepend (book_undo->undo_cache, undo_entity);
00483 }

void qof_undo_delete ( QofInstance *  inst  ) 

prepare undo data for an instance to be deleted.

Prepare for the deletion of an entity by storing ALL data in all editable parameters so that this delete operation can be undone.

Can be used within a QofEventHandler in response to QOF_EVENT_DESTROY, before the instance itself is deleted.

Definition at line 503 of file qofundo.c.

00504 {
00505     QofUndoEntity *undo_entity;
00506     QofIdType type;
00507     QofUndo *book_undo;
00508     QofBook *book;
00509 
00510     if (!instance)
00511         return;
00512     book = instance->book;
00513     book_undo = book->undo_data;
00514     // now need to store each parameter in a second entity, MODIFY.
00515     type = instance->entity.e_type;
00516     qof_class_param_foreach (type, undo_get_entity, instance);
00517     undo_entity = g_new0 (QofUndoEntity, 1);
00518     // to undo a delete, use a create.
00519     undo_entity->how = UNDO_CREATE;
00520     undo_entity->guid = qof_instance_get_guid (instance);
00521     undo_entity->type = type;
00522     book_undo->undo_cache =
00523         g_list_prepend (book_undo->undo_cache, undo_entity);
00524 }

void qof_undo_modify ( QofInstance *  inst,
const QofParam param 
)

Mark this instance parameter before modification.

Prepare undo data for this parameter of this instance. Record the initial state of this parameter of this instance in preparation for modification so that undo can reset the value if required.

Definition at line 527 of file qofundo.c.

00528 {
00529     QofBook *book;
00530     QofUndo *book_undo;
00531     QofUndoEntity *undo_entity;
00532 
00533     if (!instance || !param)
00534         return;
00535     book = instance->book;
00536     book_undo = book->undo_data;
00537     // handle if record is called without a commit.
00538     undo_entity = qof_prepare_undo (&instance->entity, param);
00539     book_undo->undo_cache =
00540         g_list_prepend (book_undo->undo_cache, undo_entity);
00541     // set the initial state that undo will reinstate.
00542     if (book_undo->index_position == 0)
00543     {
00544         book_undo->undo_list = g_list_prepend (book_undo->undo_list,
00545             qof_undo_new_operation (book, "initial"));
00546         book_undo->index_position++;
00547     }
00548 }

void qof_undo_set_param ( QofEntity ent,
const QofParam param,
gchar *  value 
)

Set a value in this parameter of the entity.

Setting an arbitrary parameter in an entity can involve repetitive string comparisons and setter function prototypes. This function accepts a QofParam (which determines the type of value) and a string representing the value. e.g. for a boolean, pass "TRUE", for a GUID pass the result of guid_to_string_buff.

Sets the undo data for this modification at the same time, calling qof_undo_modify, sets the parameter and qof_undo_commit.

Parameters:
ent An initialised QofEntity from an accessible QofBook.
param from qof_class_get_parameter
value A string representation of the required value - original type as specified in param->param_type.

Definition at line 188 of file qofundo.c.

00190 {
00191     qof_undo_modify ((QofInstance*)ent, param);
00192     set_param (ent, param, value);
00193     qof_undo_commit ((QofInstance*)ent, param);
00194 }


Generated on Mon Jul 13 05:15:16 2009 for QOF by  doxygen 1.5.9