2003-06-25 Christian Stimming <stimming@tuhh.de>

* src/gnome-utils/dialog-transfer.h: Add callback handler that is
	notified of the newly created Transaction.


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

ChangeLog

@@ -1,3 +1,8 @@
+2003-06-25  Christian Stimming  <stimming@tuhh.de>
+
+	* src/gnome-utils/dialog-transfer.h: Add callback handler that is
+	notified of the newly created Transaction.
+
 2003-06-24  Christian Stimming  <stimming@tuhh.de>
 
 	* src/import-export/hbci/*: Refactor many HBCI functions to

src/gnome-utils/dialog-transfer.c

@@ -117,6 +117,11 @@ struct _xferDialog
    * function.
    */
   gboolean *	result_p;
+
+  /* Callback funtion to notify of the newly created Transaction */
+  gnc_xfer_dialog_cb transaction_cb;
+  /* , and its user_data */
+  gpointer transaction_user_data;
 };
 
 struct _acct_list_item
@@ -1469,6 +1474,11 @@ gnc_xfer_dialog_ok_cb(GtkWidget * widget, gpointer data)
     xaccTransCommitEdit(trans);
     xaccAccountCommitEdit(from_account);
     xaccAccountCommitEdit(to_account);
+
+    /* If there is a registered callback handler that should be
+       notified of the newly created Transaction, call it now. */
+    if (xferData->transaction_cb)
+      xferData->transaction_cb(trans, xferData->transaction_user_data);
   }
 
   /* try to save this to the pricedb */
@@ -1567,6 +1577,10 @@ gnc_xfer_dialog_close_cb(GnomeDialog *dialog, gpointer data)
   XferDialog * xferData = data;
   GtkWidget *entry;
 
+  /* Notify transaction callback to unregister here */
+  if (xferData->transaction_cb)
+    xferData->transaction_cb(NULL, xferData->transaction_user_data);
+
   entry = gnc_amount_edit_gtk_entry(GNC_AMOUNT_EDIT(xferData->amount_edit));
   gtk_signal_disconnect_by_data(GTK_OBJECT(entry), xferData);
 
@@ -1796,6 +1810,7 @@ gnc_xfer_dialog (GtkWidget * parent, Account * initial)
   xferData->desc_start_selection = 0;
   xferData->desc_end_selection = 0;
   xferData->desc_didquickfill = FALSE;
+  xferData->transaction_cb = NULL;
 
   if (initial) {
     book = xaccAccountGetBook (initial);
@@ -2002,3 +2017,14 @@ gnc_xfer_dialog_quickfill_to_account(XferDialog *xferData,
   if( old != qf_to_account )
     gnc_xfer_dialog_reload_quickfill( xferData );
 }
+
+
+void gnc_xfer_dialog_set_txn_cb(XferDialog *xferData,
+				gnc_xfer_dialog_cb handler, 
+				gpointer user_data)
+{
+  g_assert(xferData);
+  xferData->transaction_cb = handler;
+  xferData->transaction_user_data = user_data;
+}
+

src/gnome-utils/dialog-transfer.h

@@ -29,8 +29,18 @@
 
 typedef struct _xferDialog XferDialog;
 
+/** Opens up a window to do an automatic transfer between accounts
+ *                                                                   
+ * Args:   parent  - the parent of the window to be created         
+ *         initial - the initial account in the from/to fields      
+ * Return: XferDialog structure                                     
+ */
 XferDialog * gnc_xfer_dialog(GtkWidget * parent, Account *initial);
 
+/** Run the dialog until the user has either successfully completed the
+ * transaction (just clicking OK doesn't always count) or clicked Cancel.
+ * Return TRUE if the transaction was a success, FALSE otherwise.
+ */
 gboolean gnc_xfer_dialog_run_until_done( XferDialog * );
 
 void gnc_xfer_dialog_close( XferDialog * );
@@ -38,11 +48,11 @@ void gnc_xfer_dialog_close( XferDialog * );
 /*********** Access routines ***********/
 void gnc_xfer_dialog_set_title( XferDialog *, const gchar * );
 
-/* set the label of the topmost frame */
+/** Set the label of the topmost frame */
 void gnc_xfer_dialog_set_information_frame_label( XferDialog *,
                                                   const gchar * );
 
-/* Add a button with a user-specified label and "clicked" callback.
+/** Add a button with a user-specified label and "clicked" callback.
  * For now this doesn't offer a lot of flexibility, but it doesn't have to.
  */
 void gnc_xfer_dialog_add_user_specified_button( XferDialog *xferData,
@@ -57,49 +67,137 @@ void gnc_xfer_dialog_set_from_account_frame_label( XferDialog *,
                                                    const gchar * );
 void gnc_xfer_dialog_set_to_account_frame_label( XferDialog *, const gchar * );
 
-/* set the buttons for "Show Income/Expense" */
+/** Set the buttons for "Show Income/Expense" */
 void gnc_xfer_dialog_set_from_show_button_active( XferDialog *, gboolean );
 void gnc_xfer_dialog_set_to_show_button_active( XferDialog *, gboolean );
 
+/**   select the from account in a xfer dialog                       */
 void gnc_xfer_dialog_select_from_account(XferDialog *xferData,
                                          Account *account);
+/**   select the to account in a xfer dialog                         */
 void gnc_xfer_dialog_select_to_account(XferDialog *xferData,
                                        Account *account);
 
 void gnc_xfer_dialog_select_from_currency(XferDialog *xferData, gnc_commodity *cur);
 void gnc_xfer_dialog_select_to_currency(XferDialog *xferData, gnc_commodity *cur);
 
-/* prevent the user from changing an account tree */
+/** Prevent changes to the from account tree in an xfer dialog     */
 void gnc_xfer_dialog_lock_from_account_tree(XferDialog *xferData );
+/** Prevent changes to the to account tree in an xfer dialog */
 void gnc_xfer_dialog_lock_to_account_tree(XferDialog *xferData );
+/** Prevent changes to the from account tree in an xfer dialog */
 void gnc_xfer_dialog_hide_from_account_tree(XferDialog *xferData );
+/** Prevent changes to the to account tree in an xfer dialog */
 void gnc_xfer_dialog_hide_to_account_tree(XferDialog *xferData );
 
+
+/**
+ *   set the amount in the given xfer dialog                        
+ *                                                                  
+ * Args:   xferData - xfer dialog structure                         
+ *         amount   - the amount to set                             
+ * Return: none                                                     
+ */
 void gnc_xfer_dialog_set_amount(XferDialog *xferData, gnc_numeric amount);
+
+/**
+ *   set the description in the given xfer dialog                   
+ *                                                                  
+ * Args:   xferData    - xfer dialog structure                      
+ *         description - the description to set                     
+ * Return: none                                                     
+ */
 void gnc_xfer_dialog_set_description(XferDialog *xferData,
                                      const char *description);
+
+/**   set the memo in the given xfer dialog                          
+ *                                                                  
+ * Args:   xferData    - xfer dialog structure                      
+ *         memo        - the memo to set                            
+ * Return: none                                                     
+ */
 void gnc_xfer_dialog_set_memo(XferDialog *xferData, const char *memo);
+
+/**
+ *   set the num in the given xfer dialog                           
+ *                                                                  
+ * Args:   xferData    - xfer dialog structure                      
+ *         num        - the num to set                              
+ * Return: none                                                     
+ */
 void gnc_xfer_dialog_set_num(XferDialog *xferData, const char *num);
+
+/**
+ *   Set the date in the given xfer dialog                          
+ *                                                                  
+ * Args:   xferData    - xfer dialog structure                      
+ *         set_date    - the date to set                            
+ * Return: none                                                     
+ */
 void gnc_xfer_dialog_set_date(XferDialog *xferData, time_t set_time);
 
-/* Set the exchange rate.  If exchange-rate is 0, then do nothing */
+/** Set the exchange rate.  If exchange-rate is 0, then do nothing */
 void gnc_xfer_dialog_set_exchange_rate(XferDialog *xferData,
 				       gnc_numeric exchange_rate);
 
-/* Indicate whether the dialog should quickfill based on the "To" account,
+/** Indicate whether the dialog should quickfill based on the "To" account,
  * rather than the default which is the "From" account.
  */
 void gnc_xfer_dialog_quickfill_to_account(XferDialog *xferData,
                                           gboolean qf_to_account );
 
-/* Indicate that this is just trying to obtain the to_amount, so make
+/**
- * the Transfer Information read-only and the dialog will NOT create a
+ *   Set the dialog as an "exchange-dialog", which means that the   
- * new transaction.  Pass in the location to store the resulting
+ *   Transfer Information frame is read-only (and the dialog        
- * exchange_rate when the dialog is complete.  The caller should call
+ *   will NOT create a transaction when it is closed).               
- * the dialog 'run' function to make sure exch_rate pointer remains
+ *
- * valid.
+ * In other words: Indicate that this is just trying to obtain the
+ * to_amount, so make the Transfer Information read-only and the
+ * dialog will NOT create a new transaction.  Pass in the location to
+ * store the resulting exchange_rate when the dialog is complete.  The
+ * caller should call the dialog 'run' function to make sure exch_rate
+ * pointer remains valid.
+ *
+ * Args:   xferData - xfer dialog structure                         
+ *         exch_rate - place to store the exchange rate at exit     
+ * Return: none                                                     
  */
 void gnc_xfer_dialog_is_exchange_dialog(XferDialog *xferData,
 					gnc_numeric * exch_rate);
 
+
+/** Callback function type for gnc_xfer_dialog_set_txn_cb().
+ *
+ * @param new_trans The newly created transaction, or NULL to notify
+ * of destruction of the xferDialog.
+ *
+ * @param user_data User-supplied pointer to some data */
+typedef void (*gnc_xfer_dialog_cb)(Transaction *new_trans,
+				   gpointer user_data);
+
+/** Register a callback function to be called with the created
+ * Transaction as soon as it is created. 
+ *
+ * Note: The caller is responsible to unregister this function in case
+ * it becomes invalid. In other words, you have to reset the handler
+ * to NULL in case this dialog exists longer than your callback
+ * function.
+ *
+ * Also note: The callback will additionally be called with
+ * transaction==NULL to notify the callback of destruction of the
+ * XferData structure.
+ *
+ * @param xferData Dialog data structure 
+ *
+ * @param handler Callback function that should be notified of the
+ * newly created Transaction 
+ *
+ * @param user_data User-supplied pointer that will be passed to
+ * handler. */
+void gnc_xfer_dialog_set_txn_cb(XferDialog *xferData,
+				gnc_xfer_dialog_cb handler, 
+				gpointer user_data);
+
+
+
 #endif