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