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
|
/*
kopeteplugindataobject.h - Kopete Plugin Data Object
Copyright (c) 2003-2004 by Olivier Goffart <ogoffart@ tiscalinet.be>
Copyright (c) 2003 by Martijn Klingens <klingens@kde.org>
Copyright (c) 2004 by Richard Smith <kde@metafoo.co.uk>
Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
*************************************************************************
* *
* This library 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 of the License, or (at your option) any later version. *
* *
*************************************************************************
*/
#ifndef KOPETEPLUGINDATAOBJECT_H
#define KOPETEPLUGINDATAOBJECT_H
#include <tqobject.h>
#include <tqdom.h>
#include "kopete_export.h"
namespace Kopete {
class Plugin;
/**
* @author Olivier Goffart <ogoffart@ tiscalinet.be>
*
* This is the base class for base elements of the contactlist.
* His purpose is to share the code between @ref Group and @ref MetaContact
*
* It handle the saving and loading of plugin data from the contactlist.
* Plugins may set custom datas to metaocntacts or groups by calling @ref setPluginData
* and may retreive them with @ref pluginData
*
* It also allow to store an icon for this element.
*/
class KOPETE_EXPORT ContactListElement : public TQObject /* public KopeteNotifyDataObject */
{
Q_OBJECT
protected:
ContactListElement( TQObject *parent = 0L, const char *name = 0L );
~ContactListElement();
public:
/**
* Set the plugin-specific data.
* The data in the provided TQMap is a set of key/value pairs.
* Note that protocol plugins usually shouldn't use this method, but
* reimplement @ref Contact::serialize() instead. This method
* is called by @ref Protocol for those classes.
*
* WARNING: This erases all old data stored for this object!
* You may want to consider the @ref setPluginData() overload
* that takes a single field as parameter.
*/
void setPluginData( Plugin *plugin, const TQMap<TQString, TQString> &value );
/**
* Convenience method to store or change only a single field of the
* plugin data. As with the other @ref setPluginData() method, protocols
* are advised not to use this method and reimplement
* @ref Contact::serialize() instead.
*
* Note that you should save the file after adding data or it will get lost.
*/
void setPluginData( Plugin *plugin, const TQString &key, const TQString &value );
/**
* Get the settings as stored previously by calls to @ref setPluginData()
*
* Note that calling this method for protocol plugins that use the
* @ref Contact::serialize() API may yield unexpected results.
*/
TQMap<TQString, TQString> pluginData( Plugin *plugin ) const;
/**
* Convenience method to retrieve only a single field from the plugin
* data. See @ref setPluginData().
*
* Note that plugin data is accessible only after it has been loaded
* from the XML file. Don't call this method before then (e.g. in
* constructors).
*/
TQString pluginData( Plugin *plugin, const TQString &key ) const;
/**
* The various icon states. Some state are reserved for Groups,
* other for metacontact.
* 'None' is the default icon.
*/
enum IconState { None, Open, Closed, Online, Away, Offline, Unknown };
/**
* return the icon for this object, in the given state.
* if there is no icon registered for this state, the None icon is used
* if available
*/
TQString icon( IconState state = None ) const;
/**
* Set the icon in the given state
* To clear an entry, set a TQString()
*/
void setIcon( const TQString &icon, IconState = None );
/**
* return if yes or no the user wants to display some custom icon.
* you can use @ref icon() to know the icons to uses
*/
bool useCustomIcon() const;
/**
* set if the user want to show custom icon he set with @ref setIcon
* this does not clear icons string if you set false
*/
void setUseCustomIcon( bool useCustomIcon );
signals:
/**
* The plugin data was changed (by a plugin)
*/
void pluginDataChanged();
/**
* The icon to use for some state has changed
*/
void iconChanged( Kopete::ContactListElement::IconState, const TQString & );
/**
* The visual appearance of some of our icons has changed
*/
void iconAppearanceChanged();
/**
* The useCustomIcon property has changed
*/
void useCustomIconChanged( bool useCustomIcon );
protected:
/**
* Return a XML representation of plugin data
*/
const TQValueList<TQDomElement> toXML();
/**
* Load plugin data from one Dom Element:
* It should be a <plugin-data> element or a <custom-icons> element. if not, nothing will happen
* @return true if something has ben loaded. false if the element was not a fine
*/
bool fromXML( const TQDomElement &element );
private:
class Private;
Private *d;
};
} //END namespace Kopete
#endif
|
