Commodity windows

Data Structures
struct	select_commodity_window
struct	commodity_window
Files
file	dialog-commodity.c
	"select" and "new" commodity windows
file	dialog-commodity.h
	"select" and "new" commodity windows
Typedefs
typedef struct select_commodity_window	SelectCommodityWindow
typedef struct commodity_window	CommodityWindow
typedef void(*	gnc_commodity_help_callback )(void)
Enumerations
enum	{ SOURCE_COL_NAME = 0, SOURCE_COL_FQ_SUPPORTED, NUM_SOURCE_COLS }
enum	dialog_commodity_mode { DIAG_COMM_CURRENCY, DIAG_COMM_NON_CURRENCY, DIAG_COMM_ALL }
Functions
void	gnc_ui_select_commodity_new_cb (GtkButton *button, gpointer user_data)
void	gnc_ui_select_commodity_changed_cb (GtkComboBoxEntry *cbe, gpointer user_data)
void	gnc_ui_select_commodity_namespace_changed_cb (GtkComboBoxEntry *cbe, gpointer user_data)
void	gnc_ui_commodity_changed_cb (GtkWidget *dummy, gpointer user_data)
void	gnc_ui_commodity_quote_info_cb (GtkWidget *w, gpointer data)
gboolean	gnc_ui_commodity_dialog_to_object (CommodityWindow *w)
void	gnc_ui_commodity_set_help_callback (gnc_commodity_help_callback cb)
void	gnc_ui_update_namespace_picker (GtkWidget *cbe, const char *init_string, dialog_commodity_mode mode)
Commodity Selection
gnc_commodity *	gnc_ui_select_commodity_modal_full (gnc_commodity *orig_sel, GtkWidget *parent, dialog_commodity_mode mode, const char *user_message, const char *cusip, const char *fullname, const char *mnemonic)
gnc_commodity *	gnc_ui_select_commodity_modal (gnc_commodity *orig_sel, GtkWidget *parent, dialog_commodity_mode mode)
Commodity Creation or Modification
gnc_commodity *	gnc_ui_new_commodity_modal_full (const char *namespace, GtkWidget *parent, const char *cusip, const char *fullname, const char *mnemonic, int fraction)
gnc_commodity *	gnc_ui_new_commodity_modal (const char *default_namespace, GtkWidget *parent)
gboolean	gnc_ui_edit_commodity_modal (gnc_commodity *commodity, GtkWidget *parent)
Auxiliary Dialog Functions
void	gnc_ui_update_commodity_picker (GtkWidget *cbe, const gchar *namespace, const gchar *init_string)
gchar *	gnc_ui_namespace_picker_ns (GtkWidget *cbe)
void	gnc_ui_update_namespace_picker (GtkWidget *cbe, const gchar *sel, dialog_commodity_mode mode)

---

Enumeration Type Documentation

enum dialog_commodity_mode

The dialog commodity types are used to determine what commodity namespaces the currency dialog will present to a user. These values can be safely changed from one release to the next. Note that if values are added, the routines in dialog-commodity.c will need to be updated to match.

Enumerator:

DIAG_COMM_CURRENCY	Dialog box should only allow selection of a currency.
DIAG_COMM_NON_CURRENCY	Dialog box should allow selection of anything but a currency.
DIAG_COMM_ALL	Dialog box should allow selection of anything.

Definition at line 46 of file dialog-commodity.h.

{
    DIAG_COMM_CURRENCY,   
    DIAG_COMM_NON_CURRENCY, 
    DIAG_COMM_ALL,        
} dialog_commodity_mode;

---

Function Documentation

void gnc_ui_commodity_set_help_callback

(

gnc_commodity_help_callback

cb

)

This function is used to set the action routine for the help button in the commodity dialog windows. If the action routine is unset, the help button will not be visible to the user.

Parameters:

cb	The function to be called when the user clicks the help button.

Definition at line 134 of file dialog-commodity.c.

{
    help_callback = cb;
}

gboolean gnc_ui_edit_commodity_modal	(	gnc_commodity *	commodity,
		GtkWidget *	parent
	)

Given an existing commodity, uses the gnc_ui_build_commodity_dialog() routine to build a basic edit dialog, then fills in the price quote information at the bottom of the dialog.

Allow the user to edit the information about a commodity. For currencies, only the price quote information may be changed. For any other commodity, all aspects of the commodity information may be changed except that the namespace may not be changed to indicate a currency. The new information overwrites any old information, so this routine may not be used to create new commodities.

Parameters:

commodity	The commodity to edit.
parent	The parent window of the new dialog.

Returns:

The newly created commodity, or NULL if the user cancelled.

Definition at line 1293 of file dialog-commodity.c.

{
    gnc_commodity *result;

    ENTER(" ");
    result = gnc_ui_common_commodity_modal(commodity, parent, NULL, NULL,
                                           NULL, NULL, 0);
    LEAVE(" ");
    return result != NULL;
}

gchar * gnc_ui_namespace_picker_ns

(

GtkWidget *

cbe

)

Given a combo box, return the currently selected namespaces.

Parameters:

cbe	The combo box of namespaces.

Returns:

The currently selected namespace.

Note:

This string is owned by the engine and must not be freed by the caller.

Definition at line 731 of file dialog-commodity.c.

{
    gchar *namespace;

    g_return_val_if_fail(GTK_IS_COMBO_BOX_ENTRY (cbe), NULL);

    namespace = gtk_combo_box_get_active_text(GTK_COMBO_BOX(cbe));

    if (safe_strcmp (namespace, GNC_COMMODITY_NS_ISO) == 0)
    {
        /* In case the user types in ISO4217, map it to CURRENCY. */
        g_free(namespace);
        return g_strdup(GNC_COMMODITY_NS_CURRENCY);
    }
    else
        return namespace;
}

gnc_commodity * gnc_ui_new_commodity_modal	(	const char *	default_namespace,
		GtkWidget *	parent
	)

Ask the user to provide the information necessary to create a new commodity.

Parameters:

default_namespace	If present, this will be the default namespace for the new commodity. This value will be ignored if it is the namespace for ISO 4217 currencies.
parent	The parent window of the new dialog.

Returns:

The newly created commodity, or NULL if the user cancelled.

Definition at line 1271 of file dialog-commodity.c.

{
    gnc_commodity *result;

    ENTER(" ");
    result = gnc_ui_common_commodity_modal(NULL, parent, default_namespace, NULL,
                                           NULL, NULL, 0);
    LEAVE(" ");
    return result;
}

gnc_commodity * gnc_ui_new_commodity_modal_full	(	const char *	namespace,
		GtkWidget *	parent,
		const char *	cusip,
		const char *	fullname,
		const char *	mnemonic,
		int	fraction
	)

Ask the user to provide the information necessary to create a new commodity.

Parameters:

namespace	If present, this will be the default namespace for the new commodity. This value will be ignored if it is the namespace for ISO 4217 currencies.
parent	The parent window of the new dialog.
cusip	If present, this will be the default exchange specific data for the new commodity.
fullname	If present, this will be the default fullname for the new commodity.
mnemonic	If present, this will be the default mnemonic for the new commodity.
fraction	If present, this will be the default fraction for the new commodity. If absent, a default of 1000 will be used.

Returns:

The newly created commodity, or NULL if the user cancelled.

Definition at line 1250 of file dialog-commodity.c.

{
    gnc_commodity *result;

    ENTER(" ");
    result = gnc_ui_common_commodity_modal(NULL, parent, namespace, cusip,
                                           fullname, mnemonic, 10000);
    LEAVE(" ");
    return result;
}

void gnc_ui_select_commodity_changed_cb	(	GtkComboBoxEntry *	cbe,
		gpointer	user_data
	)

This function is called whenever the commodity combo box is changed. Its function is to determine if a valid commodity has been selected, record the selection, and update the OK button.

Note:

This function is an internal helper function for the Commodity Selection dialog. It should not be used outside of the dialog-commodity.c file.

Parameters:

cbe	A pointer to the commodity name entry widget in the dialog.
user_data	A pointer to the data structure describing the current state of the commodity picker.

Definition at line 405 of file dialog-commodity.c.

{
    SelectCommodityWindow * w = user_data;
    gchar *namespace, *fullname;
    gboolean ok;

    ENTER("cbe=%p, user_data=%p", cbe, user_data);
    namespace = gnc_ui_namespace_picker_ns (w->namespace_combo);
    fullname = gtk_combo_box_get_active_text(GTK_COMBO_BOX(w->commodity_combo));
    DEBUG("namespace=%s, name=%s", namespace, fullname);
    w->selection = gnc_commodity_table_find_full(gnc_get_current_commodities(),
                   namespace, fullname);
    g_free(fullname);
    g_free(namespace);

    ok = (w->selection != NULL);
    gtk_widget_set_sensitive(w->ok_button, ok);
    gtk_dialog_set_default_response(GTK_DIALOG(w->dialog), ok ? 0 : 2);
    LEAVE("sensitive=%d, default = %d", ok, ok ? 0 : 2);
}

gnc_commodity * gnc_ui_select_commodity_modal	(	gnc_commodity *	orig_sel,
		GtkWidget *	parent,
		dialog_commodity_mode	mode
	)

Ask the user to select a commodity from the existing set of commodities. The user will also have the option of creating a new commodity from this dialog box.. If the user decides to create a new one, those provided values are used as default values for the new commodity.

Parameters:

orig_sel	A pointer to a commodity that should initially be selected in the dialog box.
parent	The parent window for this new selection window.
mode	Determines which namespaces the user may select a commodity from.

Returns:

The commodity selected. May or may not be a newly created commodity.

Definition at line 224 of file dialog-commodity.c.

{
    return gnc_ui_select_commodity_modal_full(orig_sel,
            parent,
            mode,
            NULL,
            NULL,
            NULL,
            NULL);
}

gnc_commodity * gnc_ui_select_commodity_modal_full	(	gnc_commodity *	orig_sel,
		GtkWidget *	parent,
		dialog_commodity_mode	mode,
		const char *	user_message,
		const char *	cusip,
		const char *	fullname,
		const char *	mnemonic
	)

Ask the user to select a commodity from the existing set of commodities. Arguments to this function determine the message placed at the top of the dialog but force no restriction on the commodities that may be chosen. The user will also have the option of creating a new commodity from this dialog box.. If the user decides to create a new one, those provided values are used as default values for the new commodity.

Parameters:

orig_sel	A pointer to a commodity that should initially be selected in the dialog box.
parent	The parent window of the new dialog.
user_message	A string that will be installed in the top of the dialog box as an instruction to the user. If NULL, a generic instruction will be used.
cusip	If present, a note will be added to the user instruction providing this exchange specific code, and this will be the default exchange specific data for any newly created commodities.
fullname	If present, a note will be added to the user instruction providing this commodity's full name, and this will be the default fullname for any newly created commodities.
mnemonic	If present, a note will be added to the user instruction providing this commodity's mnemonic, and this will be the default mnemonic for any newly created commodities.
mode	Determines which namespaces the user may select a commodity from.

Returns:

The commodity selected. May or may not be a newly created commodity.

Definition at line 144 of file dialog-commodity.c.

{
    gnc_commodity * retval = NULL;
    const gchar *initial;
    gchar *user_prompt_text;
    SelectCommodityWindow * win;
    gboolean done;
    gint value;

    win = gnc_ui_select_commodity_create(orig_sel, mode);
    win->default_cusip = cusip;
    win->default_fullname = fullname;
    win->default_mnemonic = mnemonic;

    if (parent)
        gtk_window_set_transient_for (GTK_WINDOW (win->dialog), GTK_WINDOW (parent));

    if (user_message != NULL)
        initial = user_message;
    else if ((cusip != NULL) || (fullname != NULL) || (mnemonic != NULL))
        initial = _("\nPlease select a commodity to match:");
    else
        initial = "";

    user_prompt_text =
        g_strdup_printf("%s%s%s%s%s%s%s",
                        initial,
                        fullname ? _("\nCommodity: ") : "",
                        fullname ? fullname : "",
                        /* Translators: Replace here and later CUSIP by the name of your local
                           National Securities Identifying Number
                           like gb:SEDOL, de:WKN, ch:Valorennummer, fr:SICOVAM ...
                           See http://en.wikipedia.org/wiki/ISIN for hints. */
                        cusip    ? _("\nExchange code (ISIN, CUSIP or similar): ") : "",
                        cusip    ? cusip : "",
                        mnemonic ? _("\nMnemonic (Ticker symbol or similar): ") : "",
                        mnemonic ? mnemonic : "");
    gtk_label_set_text ((GtkLabel *)(win->select_user_prompt),
                        user_prompt_text);
    g_free(user_prompt_text);

    /* Run the dialog, handling the terminal conditions. */
    done = FALSE;
    while (!done)
    {
        switch (value = gtk_dialog_run(GTK_DIALOG(win->dialog)))
        {
        case GTK_RESPONSE_OK:
            DEBUG("case OK");
            retval = win->selection;
            done = TRUE;
            break;
        case GNC_RESPONSE_NEW:
            DEBUG("case NEW");
            gnc_ui_select_commodity_new_cb(NULL, win);
            break;
        default:        /* Cancel, Escape, Close, etc. */
            DEBUG("default: %d", value);
            retval = NULL;
            done = TRUE;
            break;
        }
    }
    gtk_widget_destroy (GTK_WIDGET (win->dialog)); /* Close and destroy */
    g_free(win);

    return retval;
}

void gnc_ui_select_commodity_namespace_changed_cb	(	GtkComboBoxEntry *	cbe,
		gpointer	user_data
	)

This function is called whenever the commodity namespace combo box is changed. Its function is to update the commodity name combo box with the strings that are appropriate to the selected namespace.

Note:

This function is an internal helper function for the Commodity Selection dialog. It should not be used outside of the dialog-commodity.c file.

Parameters:

cbe	A pointer to the commodity namespace entry widget in the dialog.
user_data	A pointer to the data structure describing the current state of the commodity picker.

Definition at line 445 of file dialog-commodity.c.

{
    SelectCommodityWindow * w = user_data;
    gchar *namespace;

    ENTER("cbe=%p, user_data=%p", cbe, user_data);
    namespace = gnc_ui_namespace_picker_ns (w->namespace_combo);
    DEBUG("namespace=%s", namespace);
    gnc_ui_update_commodity_picker(w->commodity_combo, namespace, NULL);
    g_free(namespace);
    LEAVE(" ");
}

void gnc_ui_select_commodity_new_cb	(	GtkButton *	button,
		gpointer	user_data
	)

This function is called whenever the user clicks on the "New" button in the commodity picker. Its function is pop up a new dialog alling the user to create a new commodity.

Note:

This function is an internal helper function for the Commodity Selection dialog. It should not be used outside of the dialog-commodity.c file.

Parameters:

button	A pointer to the "new" button widget in the dialog.
user_data	A pointer to the data structure describing the current state of the commodity picker.

Definition at line 362 of file dialog-commodity.c.

{
    SelectCommodityWindow * w = user_data;

    gchar * namespace = gnc_ui_namespace_picker_ns (w->namespace_combo);

    const gnc_commodity * new_commodity =
        gnc_ui_new_commodity_modal_full(namespace,
                                        w->dialog,
                                        w->default_cusip,
                                        w->default_fullname,
                                        w->default_mnemonic,
                                        w->default_fraction);
    if (new_commodity)
    {
        gnc_ui_update_namespace_picker(w->namespace_combo,
                                       gnc_commodity_get_namespace(new_commodity),
                                       DIAG_COMM_ALL);
        gnc_ui_update_commodity_picker(w->commodity_combo,
                                       gnc_commodity_get_namespace(new_commodity),
                                       gnc_commodity_get_printname(new_commodity));
    }
    g_free(namespace);
}

void gnc_ui_update_commodity_picker	(	GtkWidget *	cbe,
		const gchar *	namespace,
		const gchar *	sel
	)

Given a combo box, fill in all the known commodities for the specified namespace, and then select one.

Parameters:

cbe	The widget to populate with information.
namespace	All commodities with this namespace will be added to the combo box.
sel	The commodity that should be initially selected when the combo box appears.

Definition at line 475 of file dialog-commodity.c.

{
    GList      * commodities;
    GList      * iterator = NULL;
    GList      * commodity_items = NULL;
    GtkComboBox *combo_box;
    GtkEntry *entry;
    GtkTreeModel *model;
    gnc_commodity_table *table;
    gint current = 0, match = 0;
    gchar *name;

    g_return_if_fail(GTK_IS_COMBO_BOX_ENTRY(cbe));
    g_return_if_fail(namespace);

    /* Erase the old entries */
    combo_box = GTK_COMBO_BOX(cbe);
    model = gtk_combo_box_get_model(combo_box);
    gtk_list_store_clear(GTK_LIST_STORE(model));

    /* Erase the entry text */
    entry = GTK_ENTRY(gtk_bin_get_child(GTK_BIN(combo_box)));
    gtk_editable_delete_text(GTK_EDITABLE(entry), 0, -1);

    gtk_combo_box_set_active(combo_box, -1);

    table = gnc_commodity_table_get_table (gnc_get_current_book ());
    commodities = gnc_commodity_table_get_commodities(table, namespace);
    for (iterator = commodities; iterator; iterator = iterator->next)
    {
        commodity_items =
            g_list_append(commodity_items,
                          (gpointer) gnc_commodity_get_printname(iterator->data));
    }
    g_list_free(commodities);

    commodity_items = g_list_sort(commodity_items, collate);
    for (iterator = commodity_items; iterator; iterator = iterator->next)
    {
        name = (char *)iterator->data;
        gtk_combo_box_append_text(combo_box, name);
        if (init_string && g_utf8_collate(name, init_string) == 0)
            match = current;
        current++;
    }

    gtk_combo_box_set_active(combo_box, match);
    g_list_free(commodity_items);
}

void gnc_ui_update_namespace_picker	(	GtkWidget *	cbe,
		const gchar *	sel,
		dialog_commodity_mode	mode
	)

Given a combo box, fill in the known commodity namespaces and then select one.

Parameters:

cbe	The widget to populate with information.
sel	The namespace that should be initially selected when the combo box appears.
mode	Determines which namespaces the user may select a commodity

Returns:

The currently selected namespace.

Note:

The returned string must be freed by the caller.