70
This class contains beside some type-agnostic information (flags, revision)
71
a single payload object representing its actual data. Which objects these actually
72
are depends on the mimetype of the item and the corresponding serializer plugin.
75
70
This class is implicitly shared.
78
73
<h4>Payload</h4>
76
This class contains, beside some type-agnostic information (flags, revision),
77
zero or more payload objects representing its actual data. Which objects these actually
78
are depends on the mimetype of the item and the corresponding serializer plugin(s).
81
81
Technically the only restriction on payload objects is that they have to be copyable.
82
82
For safety reasons, pointer payloads are forbidden as well though, as the
83
83
ownership would not be clear. In this case, usage of a shared pointer is
84
84
recommended (such as boost.shared_ptr or QSharedPointer).
87
Using a shared pointer is also recommended in case the payload uses polymorphic
88
types. For supported shared pointer types implicit casting is provided when possible.
87
Using a shared pointer is also required in case the payload is a polymorphic
88
type. For supported shared pointer types implicit casting is provided when possible.
91
91
When using a value-based class as payload, it is recommended to use one that does
93
93
an Akonadi.Item object imply copying of the payload object.
96
Since KDE 4.6, Item supports multiple payload types per mime type,
97
and will automatically convert between them using the serialiser
98
plugins (which is slow). It also supports mixing shared pointer
99
types, e.g. inserting a boost.shared_ptr<Foo> and extracting a
100
QSharedPointer<Foo>. Since the two shared pointer types cannot
101
share ownership of the same object, the payload class T needs to
102
provide a clone() method with the usual signature, ie.
105
<pre class="fragment">
106
virtual T * T.clone() const
110
If the class that does not have a clone() method, asking for an
111
incompatible shared pointer will throw a PayloadException.
114
Since using different shared pointer types and different payload
115
types for the same mimetype incurs slow conversions (between
116
payload types) and cloning (between shared pointer types), as well
117
as manifold memory usage (results of conversions are cached inside
118
the Item, and only destroyed when a new payload is set by the user
119
of the class), you want to restrict yourself to just one type and
120
one shared pointer type. This mechanism was mainly introduced for
121
backwards compatibility (e.g., putting in a
122
boost.shared_ptr<KCal.Incidence> and extracting a
123
QSharedPointer<KCalCore.Incidence>), so it is not optimized for
96
127
The availability of a payload of a specific type can be checked using hasPayload(),
97
128
payloads can be retrieved by using payload() and set by using setPayload(). Refer
98
129
to the documentation of those methods for more details.
102
<dl class="author" compact><dt><b>Author:</b></dt><dd> Volker Krause <vkrause@kde.org>, Till Adam <adam@kde.org> </dd></dl>
133
<dl class="author" compact><dt><b>Author:</b></dt><dd> Volker Krause <vkrause@kde.org>, Till Adam <adam@kde.org>, Marc Mutz <mutz@kde.org> </dd></dl>
104
135
<table border="0" cellpadding="0" cellspacing="0"><tr><td colspan="2"><br><h2>Enumerations</h2></td></tr>
105
136
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="#UrlType">UrlType</a> </td><td class="memItemRight" valign="bottom">{ UrlShort, UrlWithMimeType }</td></tr>
110
141
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#Item">__init__</a> (self, <a href="../akonadi/Akonadi.Item.html">Akonadi.Item</a> other)</td></tr>
111
142
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#Item">__init__</a> (self, long id)</td></tr>
112
143
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#apply">apply</a> (self, <a href="../akonadi/Akonadi.Item.html">Akonadi.Item</a> other)</td></tr>
144
<tr><td class="memItemLeft" nowrap align="right" valign="top">QVector<int> </td><td class="memItemRight" valign="bottom"><a class="el" href="#availablePayloadMetaTypeIds">availablePayloadMetaTypeIds</a> (self)</td></tr>
113
145
<tr><td class="memItemLeft" nowrap align="right" valign="top">QSet<QByteArray> </td><td class="memItemRight" valign="bottom"><a class="el" href="#availablePayloadParts">availablePayloadParts</a> (self)</td></tr>
114
146
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#clearFlag">clearFlag</a> (self, <a href="http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/qbytearray.html">QByteArray</a> name)</td></tr>
115
147
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#clearFlags">clearFlags</a> (self)</td></tr>
262
294
<dl class="since" compact><dt><b>Since:</b></dt><dd> 4.4
296
</p></div></div><a class="anchor" name="availablePayloadMetaTypeIds"></a>
297
<div class="memitem">
298
<div class="memproto">
299
<table class="memname"><tr>
300
<td class="memname">QVector<int> availablePayloadMetaTypeIds</td>
302
<td class="paramtype"> </td>
303
<td class="paramname"><em>self</em> )</td>
304
<td width="100%"> </td>
308
<div class="memdoc"><p>Returns a list of metatype-ids, describing the different
309
variants of payload that are currently contained in this item.
312
The result is always sorted (increasing ids).
264
313
</p></div></div><a class="anchor" name="availablePayloadParts"></a>
265
314
<div class="memitem">
266
315
<div class="memproto">
added
removed
python/pykde4/docs/html/akonadi/Akonadi.Item.html
