Branch data Line data Source code
1 : : /********************************************************************\
2 : : * gncBillTerm.h -- the Gnucash Billing Term interface *
3 : : * *
4 : : * This program is free software; you can redistribute it and/or *
5 : : * modify it under the terms of the GNU General Public License as *
6 : : * published by the Free Software Foundation; either version 2 of *
7 : : * the License, or (at your option) any later version. *
8 : : * *
9 : : * This program is distributed in the hope that it will be useful, *
10 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of *
11 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
12 : : * GNU General Public License for more details. *
13 : : * *
14 : : * You should have received a copy of the GNU General Public License*
15 : : * along with this program; if not, contact: *
16 : : * *
17 : : * Free Software Foundation Voice: +1-617-542-5942 *
18 : : * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
19 : : * Boston, MA 02110-1301, USA gnu@gnu.org *
20 : : * *
21 : : \********************************************************************/
22 : : /** @addtogroup Business
23 : : @{ */
24 : : /** @addtogroup BillTerm Billing Terms
25 : : Describes billing terms, that is when a bill is due, and what sort of
26 : : discount is applied (if any). The BillTerm object currently supports:
27 : : * the discount applied to a bill (absolute numeric value)
28 : : * the number of days until a discount expires
29 : : * information about the invoice due date
30 : :
31 : : This last one can be defined in multiple ways:
32 : : * using a simple number of days value: the due date is posted date
33 : : incremented with this number of days
34 : : * using the "proximo" method which is explained below:
35 : :
36 : : A proximo billing term has two parameters:
37 : : * due day: day of the month the invoice/bill will be due
38 : : * cutoff: day of the month used to decide if the due date will be
39 : : in the next month or in the month thereafter. This can be
40 : : a negative number in which case the cutoff date is relative
41 : : to the end of the month and counting backwards.
42 : : Eg: cutoff = -3 would mean 25 in February or 28 in June
43 : :
44 : : How does it work:
45 : : Assume cutoff = 19 and due day = 20
46 : :
47 : : * Example 1 post date = 14-06-2010 (European date format)
48 : : 14 is less than the cutoff of 19, so the due date will be in the next
49 : : month. Since the due day is set to 20, the due date will be
50 : : 20-07-2010
51 : :
52 : : * Example 2 post date = 22-06-2010 (European date format)
53 : : 22 is more than the cutoff of 19, so the due date will be in the month
54 : : after next month. Since the due day is set to 20, the due date will be
55 : : 20-02-2010
56 : :
57 : : @note A billing term added to an invoice is immutable, that is it
58 : : can't change any more. To achieve that a billing term is copied when
59 : : added to an invoice. This uses some internal fields to track this which
60 : : are explained in @ref ImmutableTaxTableBillTerm.
61 : :
62 : : @{ */
63 : : /** @file gncBillTerm.h
64 : : @brief Billing Term interface
65 : : @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
66 : : */
67 : :
68 : : #ifndef GNC_BILLTERM_H_
69 : : #define GNC_BILLTERM_H_
70 : :
71 : : typedef struct _gncBillTerm GncBillTerm;
72 : : typedef struct _gncBillTermClass GncBillTermClass;
73 : :
74 : : #include "qof.h"
75 : : #include "gncBusiness.h"
76 : :
77 : : #ifdef __cplusplus
78 : : extern "C" {
79 : : #endif
80 : :
81 : : #define GNC_ID_BILLTERM "gncBillTerm"
82 : :
83 : : /* --- type macros --- */
84 : : #define GNC_TYPE_BILLTERM (gnc_billterm_get_type ())
85 : : #define GNC_BILLTERM(o) \
86 : : (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_BILLTERM, GncBillTerm))
87 : : #define GNC_BILLTERM_CLASS(k) \
88 : : (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_BILLTERM, GncBillTermClass))
89 : : #define GNC_IS_BILLTERM(o) \
90 : : (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_BILLTERM))
91 : : #define GNC_IS_BILLTERM_CLASS(k) \
92 : : (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_BILLTERM))
93 : : #define GNC_BILLTERM_GET_CLASS(o) \
94 : : (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_BILLTERM, GncBillTermClass))
95 : : GType gnc_billterm_get_type(void);
96 : :
97 : : /** @name BillTerm parameter names
98 : : @{ */
99 : : #define GNC_BILLTERM_NAME "name"
100 : : #define GNC_BILLTERM_DESC "description"
101 : : #define GNC_BILLTERM_DUEDAYS "number of days due"
102 : : #define GNC_BILLTERM_DISCDAYS "number of discounted days"
103 : : #define GNC_BILLTERM_CUTOFF "cut off"
104 : : #define GNC_BILLTERM_TYPE "bill type"
105 : : #define GNC_BILLTERM_DISCOUNT "amount of discount"
106 : : #define GNC_BILLTERM_REFCOUNT "reference count"
107 : : /** @} */
108 : :
109 : : /**
110 : : * How to interpret the amount.
111 : : * You can interpret it as a VALUE or a PERCENT.
112 : : * ??? huh?
113 : : * NOTE: This enum /depends/ on starting at value 1
114 : : */
115 : : #ifndef SWIG
116 : : #define ENUM_TERMS_TYPE(_) \
117 : : _(GNC_TERM_TYPE_DAYS,=1) \
118 : : _(GNC_TERM_TYPE_PROXIMO,)
119 : :
120 : : DEFINE_ENUM(GncBillTermType, ENUM_TERMS_TYPE)
121 : : #else
122 : : typedef enum
123 : : {
124 : : GNC_TERM_TYPE_DAYS = 1,
125 : : GNC_TERM_TYPE_PROXIMO,
126 : : } GncBillTermType;
127 : : #endif
128 : :
129 : : /** @name Create/Destroy Functions
130 : : @{ */
131 : : GncBillTerm * gncBillTermCreate (QofBook *book);
132 : : void gncBillTermDestroy (GncBillTerm *term);
133 : : void gncBillTermIncRef (GncBillTerm *term);
134 : : void gncBillTermDecRef (GncBillTerm *term);
135 : :
136 : : void gncBillTermChanged (GncBillTerm *term);
137 : : void gncBillTermBeginEdit (GncBillTerm *term);
138 : : void gncBillTermCommitEdit (GncBillTerm *term);
139 : : /** @} */
140 : :
141 : : /** @name Set Functions
142 : : @{
143 : : */
144 : : void gncBillTermSetName (GncBillTerm *term, const char *name);
145 : : void gncBillTermSetDescription (GncBillTerm *term, const char *name);
146 : : void gncBillTermSetType (GncBillTerm *term, GncBillTermType type);
147 : : void gncBillTermSetDueDays (GncBillTerm *term, gint days);
148 : : void gncBillTermSetDiscountDays (GncBillTerm *term, gint days);
149 : : void gncBillTermSetDiscount (GncBillTerm *term, gnc_numeric discount);
150 : : void gncBillTermSetCutoff (GncBillTerm *term, gint cutoff);
151 : :
152 : : /** @} */
153 : :
154 : : /** @name Get Functions
155 : : @{ */
156 : : /** Return a pointer to the instance gncBillTerm that is identified
157 : : * by the guid, and is residing in the book. Returns NULL if the
158 : : * instance can't be found.
159 : : */
160 : 0 : static inline GncBillTerm * gncBillTermLookup (const QofBook *book, const GncGUID *guid)
161 : : {
162 : 0 : QOF_BOOK_RETURN_ENTITY(book, guid, GNC_ID_BILLTERM, GncBillTerm);
163 : : }
164 : :
165 : : GncBillTerm *gncBillTermLookupByName (QofBook *book, const char *name);
166 : : GList * gncBillTermGetTerms (QofBook *book);
167 : :
168 : : const char *gncBillTermGetName (const GncBillTerm *term);
169 : : const char *gncBillTermGetDescription (const GncBillTerm *term);
170 : : GncBillTermType gncBillTermGetType (const GncBillTerm *term);
171 : : gint gncBillTermGetDueDays (const GncBillTerm *term);
172 : : gint gncBillTermGetDiscountDays (const GncBillTerm *term);
173 : : gnc_numeric gncBillTermGetDiscount (const GncBillTerm *term);
174 : : gint gncBillTermGetCutoff (const GncBillTerm *term);
175 : :
176 : : gboolean gncBillTermIsDirty (const GncBillTerm *term);
177 : :
178 : : GncBillTerm *gncBillTermGetParent (const GncBillTerm *term);
179 : : GncBillTerm *gncBillTermReturnChild (GncBillTerm *term, gboolean make_new);
180 : : #define gncBillTermGetChild(t) gncBillTermReturnChild((t),FALSE)
181 : : gint64 gncBillTermGetRefcount (const GncBillTerm *term);
182 : : /** @} */
183 : :
184 : : /** @name Comparison Functions
185 : : @{ */
186 : : /** Compare BillTerms on their name for sorting. */
187 : : int gncBillTermCompare (const GncBillTerm *a, const GncBillTerm *b);
188 : : /** Check if all internal fields of a and b match. */
189 : : gboolean gncBillTermEqual(const GncBillTerm *a, const GncBillTerm *b);
190 : : /** Check only if the bill terms are "family". This is the case if
191 : : * - a and b are the same bill term
192 : : * - a is b's parent or vice versa
193 : : * - a and be are children of the same parent
194 : : *
195 : : * In practice, this check if performed by comparing the bill term's names.
196 : : * This is required to be unique per parent/children group.
197 : : */
198 : : gboolean gncBillTermIsFamily (const GncBillTerm *a, const GncBillTerm *b);
199 : : /** @} */
200 : :
201 : : /********************************************************/
202 : : /* functions to compute dates from Bill Terms */
203 : :
204 : : /* Compute the due date and discount dates from the post date */
205 : : time64 gncBillTermComputeDueDate (const GncBillTerm *term, time64 post_date);
206 : :
207 : : /* deprecated */
208 : : #define gncBillTermGetGUID(x) qof_instance_get_guid (QOF_INSTANCE(x))
209 : :
210 : : #ifdef __cplusplus
211 : : }
212 : : #endif
213 : :
214 : : #endif /* GNC_BILLTERM_H_ */
215 : : /** @} */
216 : : /** @} */
|
