mirror of
https://github.com/Gnucash/gnucash.git
synced 2025-02-25 18:55:30 -06:00
[stock-txn-asst] Add comments explaining workings.
This commit is contained in:
parent
f4ac1f40fe
commit
43b161c28b
@ -52,10 +52,37 @@
|
|||||||
|
|
||||||
static QofLogModule log_module = GNC_MOD_ASSISTANT;
|
static QofLogModule log_module = GNC_MOD_ASSISTANT;
|
||||||
|
|
||||||
|
/** The Stock Transaction Assistant guides the user through collecting the
|
||||||
|
* information needed to properly account for one of several types of securities
|
||||||
|
* investment transaction, including opening and closing long and short
|
||||||
|
* positions, oridinary and capital gains dividends, returns of capital,
|
||||||
|
* notional dividends, splits, and reverse splits. It tailors the available
|
||||||
|
* transaction types and what information it requests based on the current state
|
||||||
|
* of the account: For example, if the account holds an open short position it
|
||||||
|
* will offer buy to cover short and dividend payments to the owner of the
|
||||||
|
* stock.
|
||||||
|
*
|
||||||
|
* The Assistant is built with the Model-View-Controller pattern where
|
||||||
|
* StockAssistantModel manages the data for the transaction, StockAssistantView
|
||||||
|
* creates the visuals using a GtkAssistant and a class for each page type, and
|
||||||
|
* StockAssistantController handles user input events.
|
||||||
|
*
|
||||||
|
* Depending on type a transaction is composed of some of the following splits:
|
||||||
|
* A stock split representing the amount of units and their value in currency, a
|
||||||
|
* cash split representing the source or disposition of that value, a fees split
|
||||||
|
* representing commissions, fees, and taxes paid on the transaction, a dividend
|
||||||
|
* entry representing currency paid by the issuer to its holders (or in the case
|
||||||
|
* of a short position the currency paid by the short seller to the entity
|
||||||
|
* borrowed from compensating them for the dividend that they would have been
|
||||||
|
* paid had they not lent the shares), and two capital gains split representing
|
||||||
|
* the change in currency value from the opening transaction.
|
||||||
|
*/
|
||||||
|
|
||||||
extern "C"
|
extern "C"
|
||||||
{
|
{
|
||||||
// These functions are the GtkAssistant primary button callbacks. They're
|
// These functions are the GtkAssistant primary button callbacks. They're
|
||||||
// connected to their signals in assistant-stock-transaction.glade.
|
// connected to their signals in assistant-stock-transaction.glade so they
|
||||||
|
// mustn't be name-mangled.
|
||||||
void stock_assistant_prepare_cb (GtkAssistant *assistant, GtkWidget *page,
|
void stock_assistant_prepare_cb (GtkAssistant *assistant, GtkWidget *page,
|
||||||
gpointer user_data);
|
gpointer user_data);
|
||||||
void stock_assistant_finish_cb (GtkAssistant *assistant, gpointer user_data);
|
void stock_assistant_finish_cb (GtkAssistant *assistant, gpointer user_data);
|
||||||
@ -95,8 +122,20 @@ enum split_cols
|
|||||||
SPLIT_COL_UNITS_COLOR,
|
SPLIT_COL_UNITS_COLOR,
|
||||||
NUM_SPLIT_COLS
|
NUM_SPLIT_COLS
|
||||||
};
|
};
|
||||||
|
/* StockAssistantModel contains a (subclassed) StockTransactionEntry for each split to be created.
|
||||||
/** structures *********************************************************/
|
*
|
||||||
|
* A StockTransactionEntry contains some boolean parameters that are set from a
|
||||||
|
* fieldmask, obtained from the corresponding element in the TxnTypeInfo for the
|
||||||
|
* selected transaction type.
|
||||||
|
*
|
||||||
|
* The available transaction types are populated into
|
||||||
|
* StockAssistantModel::m_txn_types by
|
||||||
|
* StockAssistantModel::maybe_reset_txn_types() based on the state of the
|
||||||
|
* account (long, short, or empty) on the seelected
|
||||||
|
* date. StockAssistantModel::set_txn_type() then sets m_txn_type to the
|
||||||
|
* selected template and calls StockTransactionEntry::set_fieldmask() on each of
|
||||||
|
* its StockTransactionEntry members.
|
||||||
|
*/
|
||||||
|
|
||||||
enum class FieldMask : unsigned
|
enum class FieldMask : unsigned
|
||||||
{
|
{
|
||||||
@ -128,7 +167,9 @@ FieldMask operator ^(FieldMask lhs, FieldMask rhs)
|
|||||||
return static_cast<FieldMask> (static_cast<unsigned>(lhs) ^
|
return static_cast<FieldMask> (static_cast<unsigned>(lhs) ^
|
||||||
static_cast<unsigned>(rhs));
|
static_cast<unsigned>(rhs));
|
||||||
};
|
};
|
||||||
|
/* The pages displayed by the assistant and which fields are enabled on each
|
||||||
|
* page is controlled by TxnTypeInfos, one for each transaction type.
|
||||||
|
*/
|
||||||
struct TxnTypeInfo
|
struct TxnTypeInfo
|
||||||
{
|
{
|
||||||
FieldMask stock_amount;
|
FieldMask stock_amount;
|
||||||
@ -387,6 +428,10 @@ then record the reverse split.")
|
|||||||
}
|
}
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/** Possibly misnamed. Collects the required information to create a single
|
||||||
|
* split in a transaction. This is the base class; there are child classes for
|
||||||
|
* many split types.
|
||||||
|
*/
|
||||||
|
|
||||||
struct StockTransactionEntry
|
struct StockTransactionEntry
|
||||||
{
|
{
|
||||||
@ -640,6 +685,7 @@ const char *StockTransactionSplitInfo::s_missing_str = N_("(missing)");
|
|||||||
|
|
||||||
using SplitInfoVec = std::vector<StockTransactionSplitInfo>;
|
using SplitInfoVec = std::vector<StockTransactionSplitInfo>;
|
||||||
|
|
||||||
|
/** Manages the data and actions for the assistant. */
|
||||||
struct StockAssistantModel
|
struct StockAssistantModel
|
||||||
{
|
{
|
||||||
Account* m_acct;
|
Account* m_acct;
|
||||||
@ -1068,6 +1114,8 @@ get_widget (GtkBuilder *builder, const gchar * ID)
|
|||||||
return GTK_WIDGET (obj);
|
return GTK_WIDGET (obj);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Editor widgets used in assistant pages. */
|
||||||
|
|
||||||
struct GncDateEdit
|
struct GncDateEdit
|
||||||
{
|
{
|
||||||
GtkWidget *m_edit;
|
GtkWidget *m_edit;
|
||||||
@ -1234,6 +1282,8 @@ GncAccountSelector::connect (Account **acct)
|
|||||||
g_signal_connect(m_selector, "account_sel_changed", G_CALLBACK (gnc_account_sel_changed_cb), acct);
|
g_signal_connect(m_selector, "account_sel_changed", G_CALLBACK (gnc_account_sel_changed_cb), acct);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Assistant page classes. */
|
||||||
|
|
||||||
struct PageTransType {
|
struct PageTransType {
|
||||||
// transaction type page
|
// transaction type page
|
||||||
GtkWidget * m_page;
|
GtkWidget * m_page;
|
||||||
@ -1667,6 +1717,10 @@ PageCapGain::connect(Account **account, const char **memo, gnc_numeric *value)
|
|||||||
m_value.connect(value);
|
m_value.connect(value);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* The last page of the assistant shows what the resulting transaction will look
|
||||||
|
* like.
|
||||||
|
*/
|
||||||
|
/* The GncFinishtreeview lays out the transaction.*/
|
||||||
struct GncFinishTreeview
|
struct GncFinishTreeview
|
||||||
{
|
{
|
||||||
GtkWidget *m_treeview;
|
GtkWidget *m_treeview;
|
||||||
@ -1770,7 +1824,9 @@ PageFinish::prepare (GtkWidget *window, StockAssistantModel *model)
|
|||||||
}
|
}
|
||||||
gtk_label_set_text(GTK_LABEL(m_summary), summary.c_str());
|
gtk_label_set_text(GTK_LABEL(m_summary), summary.c_str());
|
||||||
gtk_assistant_set_page_complete(GTK_ASSISTANT(window), m_page, success);
|
gtk_assistant_set_page_complete(GTK_ASSISTANT(window), m_page, success);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* The StockAssistantView contains the pages and manages displaying them one at a time. */
|
||||||
|
|
||||||
struct StockAssistantView {
|
struct StockAssistantView {
|
||||||
GtkWidget * m_window;
|
GtkWidget * m_window;
|
||||||
@ -1817,6 +1873,8 @@ StockAssistantView::~StockAssistantView()
|
|||||||
DEBUG ("StockAssistantView destructor\n");
|
DEBUG ("StockAssistantView destructor\n");
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/* The StockAssistantController manages the event handlers and user input. */
|
||||||
|
|
||||||
static void connect_signals (gpointer, GtkBuilder*);
|
static void connect_signals (gpointer, GtkBuilder*);
|
||||||
|
|
||||||
struct StockAssistantController
|
struct StockAssistantController
|
||||||
@ -1838,7 +1896,8 @@ struct StockAssistantController
|
|||||||
~StockAssistantController (){ DEBUG ("StockAssistantController destructor\n"); };
|
~StockAssistantController (){ DEBUG ("StockAssistantController destructor\n"); };
|
||||||
};
|
};
|
||||||
|
|
||||||
/******* implementations ***********************************************/
|
// These callbacks must be registered with the GtkAssistant so they can't be member functions.
|
||||||
|
|
||||||
static void
|
static void
|
||||||
stock_assistant_window_destroy_cb (GtkWidget *object, gpointer user_data)
|
stock_assistant_window_destroy_cb (GtkWidget *object, gpointer user_data)
|
||||||
{
|
{
|
||||||
|
Loading…
Reference in New Issue
Block a user