summaryrefslogtreecommitdiffstats
path: root/lib/pilotAddress.h
blob: db0f18ceae6e16507ee7dd36d589a624609de596 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
#ifndef _KPILOT_PILOTADDRESS_H
#define _KPILOT_PILOTADDRESS_H
/* pilotAddress.h			KPilot
**
** Copyright (C) 1998-2001 by Dan Pilone
** Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
** Copyright (C) 2007 by Adriaan de Groot <groot@kde.org>
**
** This is a wrapper for pilot-link's address structures.
*/

/*
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU Lesser General Public License as published by
** the Free Software Foundation; either version 2.1 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU Lesser General Public License for more details.
**
** You should have received a copy of the GNU Lesser General Public License
** along with this program in a file called COPYING; if not, write to
** the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
** MA 02110-1301, USA.
*/

/*
** Bug reports and questions can be sent to kde-pim@kde.org
*/

#include <pi-macros.h>
#include <pi-address.h>

#include <tqnamespace.h>

#include "pilotRecord.h"
#include "pilotAppInfo.h"

/** Interpreted form of the AppInfo block in the address database. */
typedef PilotAppInfo<
	AddressAppInfo,
	unpack_AddressAppInfo,
	pack_AddressAppInfo> PilotAddressInfo_;

/** This class exists @em only to clear up the type mess that
*   is the field-numbers-and-indexes for phone numbers in the
*   handheld records. The standard address record has 19 fields,
*   five of which are phone fields. Those are fields 3..7 and they
*   are referred to as fields Phone1 .. Phone5. Sometimes we
*   need to act as if the phone field numbers are indeed the field
*   numbers (3..7) and sometimes we need to use those same field
*   numbers to index into a C array (0 based!) so then we map
*   field number 3 (Phone1) to a 0 index.
*
*   Also handles iteration nicely.
*
*   A phone slot value may be invalid. If so, operations on it will
*   fail (yielding invalid again) and isValid() will return @c false.
*/
class PhoneSlot
{
friend class PilotAddress;
protected:
	/** Constructor. Use the specified value for the phone slot.
	*   @p v is a field number (3..8).
	*/
	explicit PhoneSlot( const int v );

	/** Assignment operator. Set the value of the slot to
	*   the specified value @p v . This may yield an invalid
	*   phone slot.
	*/
	const PhoneSlot &operator=(const int &v);

	/** Map the slot to an offset (for use in finding the phone type
	*   for a given slot).
	* @return Offset of this slot within the phone fields.
	*/
	unsigned int toOffset() const;

	/** Map the slot to a field number. */
	unsigned int toField() const;

public:
	static const int invalid = -1; ///< Value for invalid slots. */

	/** Constructor. The slot is invalid. */
	PhoneSlot()
	{
		i = invalid;
	}

	/** Comparison operator. */
	bool operator ==( const PhoneSlot &v ) const
	{
		return v.i == i;
	}

	/** Iterator operation. Go to the next slot (or invalid when
	*   the range runs out).
	*/
	const PhoneSlot &operator++();

	/** Begin value of an iteration through the phone slots. */
	static const PhoneSlot begin();

	/** When the slot range runs out (past entryPhone5) it
	*   is invalid, so the end compares with that.
	*/
	static const PhoneSlot end();

	/** Valid slots are entryPhone1 (3) through entryPhone5 (7).
	*   @return @c true if the slot is valid.
	*/
	bool isValid() const
	{
		return (entryPhone1 <= i) && (i <= entryPhone5);
	}

	operator TQString() const;
private:
	int i;
} ;


class PilotAddressInfo : public PilotAddressInfo_
{
public:
	PilotAddressInfo(PilotDatabase *d) : PilotAddressInfo_(d)
	{
	}

	/** This resets the entire AppInfo block to one as it would be
	*   in an English-language handheld, with 3 categories and
	*   default field labels for everything.
	*/
	void resetToDefault();

	enum EPhoneType {
		eWork=0,
		eHome,
		eFax,
		eOther,
		eEmail,
		eMain,
		ePager,
		eMobile,
		eNone=-1
	} ;

	TQString phoneLabel(EPhoneType i) const;
} ;

/** @brief A wrapper class around the Address struct provided by pi-address.h
 *
 * This class allows the user to set and get address field values.
 * For everything but phone fields, the user can simply pass the
 * the pi-address enum for the index for setField() and getField() such
 * as entryLastname.
 *
 * Phone fields are a bit trickier.  The structure allows for 8 possible
 * phone fields with 5 possible slots.  That means there could be three
 * fields that don't have available storage. The setPhoneField() method
 * will attempt to store the extra fields in a custom field if there
 * is an overflow.
 *
 * There are eight possible fields for 5 view slots:
 * - fields: Work, Home, Fax, Other, Pager, Mobile, E-mail, Main
 * - slots: entryPhone1, entryPhone2, entryPhone3, entryPhone4, entryPhone5
 *
 * Internally in the pilot-link library, the AddressAppInfo phone
 * array stores the strings for the eight possible phone values.
 * Their English string values are :
 * - phone[0] = Work
 * - phone[1] = Home
 * - phone[2] = Fax
 * - phone[3] = Other
 * - phone[4] = E-mail
 * - phone[5] = Main
 * - phone[6] = Pager
 * - phone[7] = Mobile
 *
 * Apparently, this order is kept for all languages, just with localized
 * strings.  The implementation of the internal methods will assume
 * this order is kept. In other languages, main can replaced with
 * Corporation.
 */
class KDE_EXPORT PilotAddress : public PilotRecordBase
{
public:
	PilotAddress(PilotRecord *rec = 0L);
	PilotAddress(const PilotAddress &copyFrom);
	PilotAddress& operator=( const PilotAddress &r );
	bool operator==(const PilotAddress &r);

	virtual ~PilotAddress();

	/** Returns a text representation of the address. If @p richText is true, the
	 *  text will be formatted with TQt-HTML tags. The AppInfo structure @p info
	 *  is used to figure out the phone labels; if it is NULL then bogus labels are
	 *  used to identify phone types.
	 */
	TQString getTextRepresentation(const PilotAddressInfo *info, TQt::TextFormat richText) const;

	/**
	*   @param text set the field value
	*   @param field int values associated with the enum defined in
	*  pi-address.h.
	*  The copied possible enum's are: (copied from pi-address.h on 1/12/01)
	*  enum { entryLastname, entryFirstname, entryCompany,
	*  entryPhone1, entryPhone2, entryPhone3, entryPhone4, entryPhone5,
	*  entryAddress, entryCity, entryState, entryZip, entryCountry,
	*  entryTitle, entryCustom1, entryCustom2, entryCustom3, entryCustom4,
	*  entryNote };
	*/
	void setField(int field, const TQString &text);
	/** Set a field @p i to a given text value. Uses the phone slots only. */
	void setField(const PhoneSlot &i, const TQString &t)
	{
		if (i.isValid())
		{
			setField(i.toField(),t);
		}
	}

	/** Returns the text value of a given field @p field (or TQString()
	*   if there is no such field).
	*/
	TQString getField(int field) const;
	/** Returns the value of the phone field @p i . */
	TQString getField(const PhoneSlot &i) const
	{
		return i.isValid() ? getField(i.toField()) : TQString();
	}

	/**
	*   Return list of all email addresses.  This will search through our "phone"
	*   fields and will return only those which are e-mail addresses.
	*/
	TQStringList getEmails() const;
	void setEmails(const TQStringList &emails);

	enum PhoneHandlingFlags
	{
		NoFlags=0, ///< No special handling
		Replace    ///< Replace existing entries of same type
	} ;

	/**
	*  @param type is the type of phone
	*  @param checkCustom4 flag if true, checks the entryCustom4 field
	*  for extra phone fields
	*  @return the field associated with the type
	*/
	TQString getPhoneField(PilotAddressInfo::EPhoneType type) const;

	/**
	*  @param type is the type of phone
	*  @param field is value to store
	*  @param overflowCustom is true, and entryPhone1 to entryPhone5 is full
	*  it will use entryCustom4 field to store the field
	*  @param overwriteExisting is true, it will overwrite an existing record-type
	*  with the field, else it will always search for the first available slot
	 * @return index of the field that this information was set to
	*/
	PhoneSlot setPhoneField(PilotAddressInfo::EPhoneType type, const TQString &value, PhoneHandlingFlags flags);

	/**
	* Returns the slot of the phone number
	* selected by the user to be shown in the
	* overview of addresses.
	*
	* @return Slot of phone entry (between entryPhone1 and entryPhone5)
	*/
	PhoneSlot getShownPhone() const;

	/**
	* Set the shown phone (the one preferred by the user for display
	* on the handheld's overview page) to the @em type (not index)
	* indicated. Looks through the phone entries of this record to
	* find the first one one of this type.
	*
	* @return Slot of phone entry.
	*
	* @note Sets the shown phone to the first entry if no field of
	*       type @p phoneType can be found @em and no Home phone
	*       field (the fallback) can be found either.
	*/
	PhoneSlot setShownPhone(PilotAddressInfo::EPhoneType phoneType);

	/**
	* Set the shown phone (the one preferred by the user for display
	* on the handheld's overview page) to the given @p slot .
	*
	* @return @p v
	*/
	const PhoneSlot &setShownPhone(const PhoneSlot &v);

	/** Get the phone type (label) for a given field @p field
	*   in the record. The @p field must be within the
	*   phone range (entryPhone1 .. entryPhone5).
	*
	* @return Phone type for phone field @p field .
	* @return @c eNone (fake phone type) if @p field is invalid.
	*/
	PilotAddressInfo::EPhoneType getPhoneType(const PhoneSlot &field) const;

	PilotRecord *pack() const;

	const struct Address *address() const { return &fAddressInfo; } ;


protected:
	// Get the pointers in cases where no conversion to
	// unicode is desired.
	//
	const char *getFieldP(int field) const
	{
		return fAddressInfo.entry[field];
	}

private:
	void _copyAddressInfo(const struct Address &copyFrom);
	PhoneSlot _getNextEmptyPhoneSlot() const;

	/** @return entryPhone1 to entryPhone5 if the appTypeNum number is
	*  found in the phoneLabel array; return -1 if not found
	*/
	PhoneSlot _findPhoneFieldSlot(PilotAddressInfo::EPhoneType t) const;

	struct Address fAddressInfo;
};




#endif