QOF  0.8.7
Files | Macros | Functions
Undo: Track and undo or redo entity changes

Files

file  qofundo.h
 QOF undo handling.
 

Macros

#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. More...
 
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. More...
 
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 More...
 
gboolean qof_book_can_redo (QofBook *book)
 event handler for redo widget More...
 
void qof_book_start_operation (QofBook *book, gchar *label)
 Start recording operation. More...
 
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.

  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 420 of file qofundo.c.

421 {
422  QofUndo *book_undo;
423  gint length;
424 
425  book_undo = book->undo_data;
426  length = g_list_length (book_undo->undo_list);
427  if ((book_undo->index_position == length) || (length == 0))
428  return FALSE;
429  return TRUE;
430 }
QofUndo * undo_data
Definition: qofbook-p.h:90
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 407 of file qofundo.c.

408 {
409  QofUndo *book_undo;
410  gint length;
411 
412  book_undo = book->undo_data;
413  length = g_list_length (book_undo->undo_list);
414  if ((book_undo->index_position == 0) || (length == 0))
415  return FALSE;
416  return TRUE;
417 }
QofUndo * undo_data
Definition: qofbook-p.h:90
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 387 of file qofundo.c.

388 {
389  QofUndoOperation *operation;
390  QofUndo *book_undo;
391 
392  if (!book)
393  return;
394  book_undo = book->undo_data;
395  while (book_undo != NULL)
396  {
397  operation = (QofUndoOperation *) book_undo->undo_list->data;
398  if(operation->entity_list)
399  g_list_free (operation->entity_list);
400  book_undo->undo_list = g_list_next (book_undo->undo_list);
401  }
402  book_undo->index_position = 0;
403  g_free (book_undo->undo_label);
404 }
QofUndo * undo_data
Definition: qofbook-p.h:90
void qof_book_start_operation ( QofBook book,
gchar *  label 
)

Start recording operation.

Definition at line 565 of file qofundo.c.

566 {
567  QofUndo *book_undo;
568 
569  book_undo = book->undo_data;
570  if (book_undo->undo_operation_open && book_undo->undo_cache)
571  {
572  g_list_free (book_undo->undo_cache);
573  book_undo->undo_operation_open = FALSE;
574  if (book_undo->undo_label)
575  g_free (book_undo->undo_label);
576  }
577  book_undo->undo_label = g_strdup (label);
578  book_undo->undo_operation_open = TRUE;
579 }
QofUndo * undo_data
Definition: qofbook-p.h:90
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 549 of file qofundo.c.

550 {
551  QofUndoEntity *undo_entity;
552  QofUndo *book_undo;
553  QofBook *book;
554 
555  if (!instance || !param)
556  return;
557  book = instance->book;
558  book_undo = book->undo_data;
559  undo_entity = qof_prepare_undo (&instance->entity, param);
560  book_undo->undo_cache =
561  g_list_prepend (book_undo->undo_cache, undo_entity);
562 }
QofUndo * undo_data
Definition: qofbook-p.h:90
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 464 of file qofundo.c.

465 {
466  QofUndoEntity *undo_entity;
467  QofBook *book;
468  QofUndo *book_undo;
469 
470  if (!instance)
471  return;
472  book = instance->book;
473  book_undo = book->undo_data;
474  undo_entity = g_new0 (QofUndoEntity, 1);
475  // to undo a create, use a delete.
476  undo_entity->how = UNDO_DELETE;
477  undo_entity->guid = qof_instance_get_guid (instance);
478  undo_entity->type = instance->entity.e_type;
479  book_undo->undo_cache =
480  g_list_prepend (book_undo->undo_cache, undo_entity);
481 }
QofUndo * undo_data
Definition: qofbook-p.h:90
const GUID * qof_instance_get_guid(QofInstance *inst)
Definition: qofinstance.c:79
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 501 of file qofundo.c.

502 {
503  QofUndoEntity *undo_entity;
504  QofIdType type;
505  QofUndo *book_undo;
506  QofBook *book;
507 
508  if (!instance)
509  return;
510  book = instance->book;
511  book_undo = book->undo_data;
512  // now need to store each parameter in a second entity, MODIFY.
513  type = instance->entity.e_type;
514  qof_class_param_foreach (type, undo_get_entity, instance);
515  undo_entity = g_new0 (QofUndoEntity, 1);
516  // to undo a delete, use a create.
517  undo_entity->how = UNDO_CREATE;
518  undo_entity->guid = qof_instance_get_guid (instance);
519  undo_entity->type = type;
520  book_undo->undo_cache =
521  g_list_prepend (book_undo->undo_cache, undo_entity);
522 }
const gchar * QofIdType
Definition: qofid.h:81
void qof_class_param_foreach(QofIdTypeConst obj_name, QofParamForeachCB cb, gpointer user_data)
Definition: qofclass.c:268
QofUndo * undo_data
Definition: qofbook-p.h:90
const GUID * qof_instance_get_guid(QofInstance *inst)
Definition: qofinstance.c:79
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 525 of file qofundo.c.

526 {
527  QofBook *book;
528  QofUndo *book_undo;
529  QofUndoEntity *undo_entity;
530 
531  if (!instance || !param)
532  return;
533  book = instance->book;
534  book_undo = book->undo_data;
535  // handle if record is called without a commit.
536  undo_entity = qof_prepare_undo (&instance->entity, param);
537  book_undo->undo_cache =
538  g_list_prepend (book_undo->undo_cache, undo_entity);
539  // set the initial state that undo will reinstate.
540  if (book_undo->index_position == 0)
541  {
542  book_undo->undo_list = g_list_prepend (book_undo->undo_list,
543  qof_undo_new_operation (book, "initial"));
544  book_undo->index_position++;
545  }
546 }
QofUndo * undo_data
Definition: qofbook-p.h:90
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
entAn initialised QofEntity from an accessible QofBook.
paramfrom qof_class_get_parameter
valueA string representation of the required value - original type as specified in param->param_type.

Definition at line 188 of file qofundo.c.

190 {
191  qof_undo_modify ((QofInstance*)ent, param);
192  set_param (ent, param, value);
193  qof_undo_commit ((QofInstance*)ent, param);
194 }
void qof_undo_commit(QofInstance *instance, const QofParam *param)
Definition: qofundo.c:549
void qof_undo_modify(QofInstance *instance, const QofParam *param)
Definition: qofundo.c:525