add preliminary work on transaction voiding.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@5447 57a11ea4-9604-0410-9ed3-97b8803252fd

ChangeLog

@@ -1,3 +1,10 @@
+2001-10-01  Robert Graham Merkel  <rgmerk@mira.net>
+
+	* src/engine/Transaction.{ch} (xaccTransVoid), (xaccTransGetVoidStatus),
+	(xaccTransGetVoidReason), (xaccSplitVoidFormerAmount): new functions.
+
+	* src/engine/kvp_doc.txt: add new entries related to transaction voiding.
+
 2001-09-30  Josh Sled  <jsled@asynchronous.org>
 
 	* src/gnome/dialog-sxsincelast.c: Displays

src/engine/Transaction.c

@@ -65,6 +65,9 @@
  */
 int force_double_entry = 0;
 
+const char *void_reason_str = "void-reason";
+const char *void_former_amt_str = "void-former-amount";
+
 #define PRICE_SIGFIGS 6
 
 /* This static indicates the debugging module that this .o belongs to.  */
@@ -2548,5 +2551,105 @@ xaccIsPeerSplit (Split *sa, Split *sb)
    return 0;
 }
 
+
+/********************************************************************\
+\********************************************************************/
+
+void
+xaccTransVoid(Transaction *transaction,
+	      const char *reason)
+{
+  kvp_frame *frame;
+  kvp_value *val;
+  gnc_numeric amt, zero;
+  GList *split_list;
+  Split *split;
+  g_return_if_fail(transaction && reason);
+
+  zero = gnc_numeric_zero();
+  frame = xaccTransGetSlots(transaction);
+
+  val = kvp_value_new_string(reason);
+
+  kvp_frame_set_slot_nc(frame, 
+			void_reason_str,
+			val);
+
+  
+  for(  split_list = xaccTransGetSplitList(transaction); 
+	split_list; 
+	split_list = g_list_next(split_list))
+  {
+    split = split_list->data;
+    
+    amt = xaccSplitGetAmount(split);
+
+    val = kvp_value_new_gnc_numeric(amt);
+
+    frame = xaccSplitGetSlots(split);
+    
+    kvp_frame_set_slot_nc(frame, void_former_amt_str, val);
+    
+    xaccSplitSetAmount(split, zero);
+    xaccSplitSetReconcile(split, VREC);
+  }
+
+  return;
+}
+
+gboolean 
+xaccTransGetVoidStatus(Transaction *trans)
+{
+  kvp_frame *frame;
+
+  
+  g_return_val_if_fail(trans, FALSE);
+
+  frame = xaccTransGetSlots(trans);
+
+  return (gboolean) kvp_frame_get_slot(frame, void_reason_str);
+
+}
+
+char *
+xaccTransGetVoidReason(Transaction *trans)
+{
+  kvp_frame *frame;
+  kvp_value *val;
+  char *reason;
+  g_return_val_if_fail(trans, NULL);
+
+  frame = xaccTransGetSlots(trans);
+
+  val = kvp_frame_get_slot(frame, void_reason_str);
+  
+  if(val)
+  {
+    reason = kvp_value_get_string(val);
+    return reason;
+  }
+
+  return NULL;
+}
+
+gnc_numeric xaccSplitVoidFormerAmount(Split *split)
+{
+  kvp_frame *frame;
+  kvp_value *val;
+  gnc_numeric amt = gnc_numeric_zero();
+  g_return_val_if_fail(split, amt);
+
+  frame = xaccSplitGetSlots(split);
+
+  val = kvp_frame_get_slot(frame, void_former_amt_str);
+  
+  if(val)
+  {
+    amt = kvp_value_get_numeric(val);
+  }
+
+  return amt;
+  
+}
 /************************ END OF ************************************\
 \************************* FILE *************************************/

src/engine/Transaction.h

@@ -39,6 +39,7 @@
 #define YREC 'y'              /* The Split has been reconciled     */
 #define FREC 'f'              /* frozen into accounting period     */
 #define NREC 'n'              /* not reconciled or cleared         */
+#define VREC 'v'              /* split is void                     */
 
 /** STRUCTS *********************************************************/
 
@@ -476,4 +477,23 @@ Split * xaccSplitGetOtherSplit (Split *split);
  */
 int xaccIsPeerSplit (Split *split_1, Split *split_2);
 
+
+/*
+ * xaccTransactionVoid voids a transaction.  A void transaction
+ * has no values, is unaffected by reconciliation, and, by default
+ * is not included in any queries.  A voided transaction 
+ * should not be altered (and we'll try to make it so it can't be).
+ * voiding is irreversible.  Once voided, a transaction cannot be
+ * un-voided.
+ */
+
+void xaccTransVoid(Transaction *transaction, 
+			 const char *reason);
+
+gboolean xaccTransGetVoidStatus(Transaction *transaction);
+
+char *xaccTransGetVoidReason(Transaction *transaction);
+
+gnc_numeric xaccSplitVoidFormerAmount(Split *split);
+
 #endif /* XACC_TRANSACTION_H */

src/engine/kvp_doc.txt

@@ -187,3 +187,17 @@ Entities: All
 Use: This frame is used to store keys which are editable directly by
      the user. The program should not attach any semantics to keys
      under this frame.
+
+Name: void-reason
+Type: string
+Entities: Transaction
+Use: This string is used to store the reason why a transaction has been 
+voided.  Note that it should only exist if the transaction has been voided.
+
+Name: void-former-amount
+Type: gnc_numeric
+Entities: Split
+Use: To store the amount of the this split before it was voided.  Note
+that it should only exist if the parent transaction has been voided (but
+checking the reconcile status of the split is a more direct way of finding
+out a split has been voided).