1 /******************************************************************** 2 * dialog-commodity.h -- "select" and "new" commodity windows * 3 * (GnuCash) * 4 * Copyright (C) 2000 Bill Gribble <grib@billgribble.com> * 5 * Copyright (c) 2006 David Hampton <hampton@employees.org> * 6 * * 7 * This program is free software; you can redistribute it and/or * 8 * modify it under the terms of the GNU General Public License as * 9 * published by the Free Software Foundation; either version 2 of * 10 * the License, or (at your option) any later version. * 11 * * 12 * This program is distributed in the hope that it will be useful, * 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 15 * GNU General Public License for more details. * 16 * * 17 * You should have received a copy of the GNU General Public License* 18 * along with this program; if not, contact: * 19 * * 20 * Free Software Foundation Voice: +1-617-542-5942 * 21 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 22 * Boston, MA 02110-1301, USA gnu@gnu.org * 23 ********************************************************************/ 24 25 /** @addtogroup GUI 26 @{ */ 27 /** @addtogroup GuiCommodity Commodity windows 28 @{ */ 29 /** @file dialog-commodity.h 30 @brief "select" and "new" commodity windows 31 @author Copyright (C) 2000 Bill Gribble <grib@billgribble.com> 32 */ 33 34 #ifndef GNC_DIALOG_COMMODITY_H 35 #define GNC_DIALOG_COMMODITY_H 36 37 #include <gtk/gtk.h> 38 #include "gnc-commodity.h" 39 40 /** The dialog commodity types are used to determine what commodity 41 * namespaces the currency dialog will present to a user. These 42 * values can be safely changed from one release to the next. Note 43 * that if values are added, the routines in dialog-commodity.c will 44 * need to be updated to match. 45 */ 46 typedef enum 47 { 48 DIAG_COMM_CURRENCY, /**< Dialog box should only allow selection 49 of a currency. */ 50 DIAG_COMM_NON_CURRENCY, /**< Dialog box should allow selection of 51 anything but a currency. */ 52 DIAG_COMM_NON_CURRENCY_SELECT, /**< Dialog box should allow selection of 53 * anything but a currency and should include 54 * the "ALL" namespace to display all such 55 * commodities in a single list. */ 56 DIAG_COMM_ALL, /**< Dialog box should allow selection of 57 anything. */ 58 } dialog_commodity_mode; 59 60 61 /** @name Commodity Selection */ 62 /** @{ */ 63 64 /** Ask the user to select a commodity from the existing set of 65 * commodities. Arguments to this function determine the message 66 * placed at the top of the dialog but force no restriction on the 67 * commodities that may be chosen. The user will also have the 68 * option of creating a new commodity from this dialog box.. If the 69 * user decides to create a new one, those provided values are used 70 * as default values for the new commodity. 71 * 72 * @param orig_sel A pointer to a commodity that should initially be 73 * selected in the dialog box. 74 * 75 * @param parent The parent window of the new dialog. 76 * 77 * @param user_message A string that will be installed in the top of 78 * the dialog box as an instruction to the user. If NULL, a generic 79 * instruction will be used. 80 * 81 * @param cusip If present, a note will be added to the user 82 * instruction providing this exchange specific code, and this will 83 * be the default exchange specific data for any newly created 84 * commodities. 85 * 86 * @param fullname If present, a note will be added to the user 87 * instruction providing this commodity's full name, and this will be 88 * the default fullname for any newly created commodities. 89 * 90 * @param mnemonic If present, a note will be added to the user 91 * instruction providing this commodity's mnemonic, and this will be 92 * the default mnemonic for any newly created commodities. 93 * 94 * @param mode Determines which namespaces the user may select a 95 * commodity from. 96 * 97 * @return The commodity selected. May or may not be a newly created 98 * commodity. 99 */ 100 gnc_commodity * 101 gnc_ui_select_commodity_modal_full(gnc_commodity * orig_sel, 102 GtkWidget * parent, 103 dialog_commodity_mode mode, 104 const char * user_message, 105 const char * cusip, 106 const char * fullname, 107 const char * mnemonic); 108 109 110 /** Ask the user to select a commodity from the existing set of 111 * commodities. The user will also have the 112 * option of creating a new commodity from this dialog box.. If the 113 * user decides to create a new one, those provided values are used 114 * as default values for the new commodity. 115 * 116 * @param orig_sel A pointer to a commodity that should initially be 117 * selected in the dialog box. 118 * 119 * @param parent The parent window for this new selection window. 120 * 121 * @param mode Determines which namespaces the user may select a 122 * commodity from. 123 * 124 * @return The commodity selected. May or may not be a newly created 125 * commodity. 126 */ 127 gnc_commodity * 128 gnc_ui_select_commodity_modal(gnc_commodity * orig_sel, 129 GtkWidget * parent, 130 dialog_commodity_mode mode); 131 /** @} */ 132 133 134 /** @name Commodity Creation or Modification */ 135 /** @{ */ 136 137 /** Ask the user to provide the information necessary to create a new 138 * commodity. 139 * 140 * @param namespace If present, this will be the default namespace 141 * for the new commodity. This value will be ignored if it is the 142 * namespace for ISO 4217 currencies. 143 * 144 * @param parent The parent window of the new dialog. 145 * 146 * @param cusip If present, this will be the default exchange 147 * specific data for the new commodity. 148 * 149 * @param fullname If present, this will be the default fullname for 150 * the new commodity. 151 * 152 * @param mnemonic If present, this will be the default mnemonic for 153 * the new commodity. 154 * 155 * @param user_symbol If present, this will be the default user symbol 156 * for the new commodity. 157 * 158 * @param fraction If present, this will be the default fraction for 159 * the new commodity. If absent, a default of 1000 will be used. 160 * 161 * @return The newly created commodity, or NULL if the user cancelled. 162 */ 163 gnc_commodity * 164 gnc_ui_new_commodity_modal_full(const char * name_space, 165 GtkWidget * parent, 166 const char * cusip, 167 const char * fullname, 168 const char * mnemonic, 169 const char * user_symbol, 170 int fraction); 171 172 /** Ask the user to provide the information necessary to create a new 173 * commodity. 174 * 175 * @param default_namespace If present, this will be the default namespace 176 * for the new commodity. This value will be ignored if it is the 177 * namespace for ISO 4217 currencies. 178 * 179 * @param parent The parent window of the new dialog. 180 * 181 * @return The newly created commodity, or NULL if the user cancelled. 182 */ 183 gnc_commodity * 184 gnc_ui_new_commodity_modal(const char * default_namespace, 185 GtkWidget * parent); 186 187 /** Allow the user to edit the information about a commodity. For 188 * currencies, only the price quote information may be changed. For 189 * any other commodity, all aspects of the commodity information may 190 * be changed except that the namespace may not be changed to 191 * indicate a currency. The new information overwrites any old 192 * information, so this routine may not be used to create new 193 * commodities. 194 * 195 * @param commodity The commodity to edit. 196 * 197 * @param parent The parent window of the new dialog. 198 * 199 * @return The newly created commodity, or NULL if the user cancelled. 200 */ 201 gboolean 202 gnc_ui_edit_commodity_modal(gnc_commodity *commodity, 203 GtkWidget * parent); 204 /** @} */ 205 206 207 /** @name Auxiliary Dialog Functions */ 208 /** @{ */ 209 210 /** Given a combo box, fill in the known commodity namespaces and then 211 * select one. 212 * 213 * @param cbwe The widget to populate with information. 214 * 215 * @param sel The namespace that should be initially selected when 216 * the combo box appears. 217 * 218 * @param mode Determines in which namespaces the user may select a 219 * commodity 220 */ 221 void gnc_ui_update_namespace_picker(GtkWidget *cbwe, 222 const gchar *sel, 223 dialog_commodity_mode mode); 224 225 /** Given a combo box, return the currently selected namespaces. 226 * 227 * @param cbwe The combo box of namespaces. 228 * 229 * @return The currently selected namespace. 230 * 231 * @note This string must be freed by with g_free. 232 */ 233 gchar *gnc_ui_namespace_picker_ns (GtkWidget *cbwe); 234 235 /** Given a combo box, fill in all the known commodities for the 236 * specified namespace, and then select one. 237 * 238 * @param cbwe The widget to populate with information. 239 * 240 * @param namespace All commodities with this namespace will be added 241 * to the combo box. 242 * 243 * @param sel The commodity that should be initially selected when 244 * the combo box appears. 245 */ 246 void gnc_ui_update_commodity_picker(GtkWidget *cbwe, 247 const gchar *name_space, 248 const gchar *sel); 249 /** @} */ 250 251 #endif 252 /** @} */ 253 /** @} */ 254