1 | /* This file is part of the KDE project |
2 | Copyright (C) 2000 David Faure <faure@kde.org> |
3 | |
4 | This program is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License. |
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 GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this program; see the file COPYING. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KUrlDRAG_H |
21 | #define KUrlDRAG_H |
22 | |
23 | #include <kde3support_export.h> |
24 | #include <kurl.h> |
25 | |
26 | #include <QtCore/QStringList> |
27 | #include <Qt3Support/Q3ColorDrag> |
28 | |
29 | class QMimeSource; |
30 | |
31 | class K3URLDragPrivate; |
32 | /** |
33 | * This class is to be used instead of Q3UriDrag when using KUrl. |
34 | * The reason is: Q3UriDrag (and the XDND/W3C standards) expect URLs to |
35 | * be encoded in UTF-8 (unicode), but KUrl uses the current locale |
36 | * by default. |
37 | * The other reasons for using this class are: |
38 | * @li it exports text/plain (for dropping/pasting into lineedits, mails etc.) |
39 | * @li it has support for metadata, shipped as part of the dragobject |
40 | * This is important, for instance to set a correct HTTP referrer (some websites |
41 | * require it for downloading e.g. an image). |
42 | * |
43 | * To create a drag object, use the K3URLDrag constructor. |
44 | * To handle drops, use Q3UriDrag::canDecode() and K3URLDrag::decode() |
45 | */ |
46 | class KDE3SUPPORT_EXPORT K3URLDrag : public Q3UriDrag |
47 | { |
48 | public: |
49 | /** |
50 | * Constructs an object to drag the list of URLs in @p urls. |
51 | * The @p dragSource and @p name arguments are passed on to Q3UriDrag, |
52 | * and the list of urls is converted to UTF-8 before being passed |
53 | * to Q3UriDrag. |
54 | * @param urls the list of URLs |
55 | * @param dragSource the parent of the QObject. Should be set when doing drag-n-drop, |
56 | * but should be 0 when copying to the clipboard |
57 | */ |
58 | K3URLDrag( const KUrl::List &urls, QWidget* dragSource = 0 ); |
59 | /** |
60 | * Constructs an object to drag the list of URLs in @p urls. |
61 | * This version also includes metadata. |
62 | * @param urls the list of URLs |
63 | * @param metaData a map containing meta data |
64 | * @param dragSource the parent of the QObject. Should be set when doing drag-n-drop, |
65 | * but should be 0 when copying to the clipboard |
66 | * @see metaData() |
67 | */ |
68 | K3URLDrag( const KUrl::List &urls, const QMap<QString, QString>& metaData, |
69 | QWidget* dragSource = 0 ); |
70 | |
71 | virtual ~K3URLDrag(); |
72 | |
73 | /** |
74 | * By default, K3URLDrag also exports the URLs as plain text, for e.g. dropping onto a text editor. |
75 | * But in some cases this might not be wanted, e.g. if using the K3URLDrag in a KMultipleDrag |
76 | * and another component of the multiple-drag provides better plain text data. |
77 | * In such a case, setExportAsText( false ) should be called. |
78 | */ |
79 | void setExportAsText( bool exp ); |
80 | |
81 | /** |
82 | * @deprecated Is equivalent with "new K3URLDrag(urls, dragSource, name)". |
83 | */ |
84 | static K3URLDrag * newDrag( const KUrl::List &urls, QWidget* dragSource = 0 ); |
85 | |
86 | /** |
87 | * @deprecated Is equivalent with "new K3URLDrag(urls, metaData, dragSource, name)". |
88 | */ |
89 | static K3URLDrag * newDrag( const KUrl::List &urls, |
90 | const QMap<QString, QString>& metaData, |
91 | QWidget* dragSource = 0 ); |
92 | |
93 | /** |
94 | * Meta-data to associate with those URLs. |
95 | * This is an alternative way of setting the metadata: |
96 | * either use the constructor to pass it all at once, or use |
97 | * drag->metaData()["key"] = data; |
98 | * @see KIO::TransferJob |
99 | */ |
100 | QMap<QString, QString> &metaData(); |
101 | |
102 | /** |
103 | * Convenience method that decodes the contents of @p e |
104 | * into a list of KUrls. Decoding will fail if at least one decoded value |
105 | * is not a valid KUrl. |
106 | * @param e the mime source |
107 | * @param urls the list of urls will be written here |
108 | * @return true if successful, false otherwise |
109 | */ |
110 | static bool decode( const QMimeSource *e, KUrl::List &urls ); |
111 | |
112 | /** |
113 | * Convenience method that decodes the contents of @p e |
114 | * into a list of KUrls and a set of metadata. Decoding will fail if |
115 | * at least one decoded value is not a valid KUrl. |
116 | * You should be using this one, if possible. |
117 | * @param e the mime source |
118 | * @param urls the list of urls will be written here |
119 | * @param metaData the metadata map will be written here |
120 | * @return true if successful, false otherwise |
121 | */ |
122 | static bool decode( const QMimeSource *e, KUrl::List &urls, QMap<QString,QString>& metaData ); |
123 | |
124 | /** |
125 | * Converts a URL to a string representation suitable for dragging. |
126 | */ |
127 | static QString urlToString(const KUrl &url); |
128 | |
129 | /** |
130 | * Converts a string used for dragging to a URL. |
131 | */ |
132 | static KUrl stringToUrl(const QByteArray &s); |
133 | |
134 | #ifdef Q_WS_QWS |
135 | /** |
136 | * Convenience method that decodes the contents of @p e |
137 | * into a list of KUrls for Qt versions without a MIME clipboard. |
138 | * Decoding will fail if at least one value in the list is not a valid KUrl. |
139 | */ |
140 | static bool decode( QStringList const &e, KUrl::List &uris ); |
141 | #endif |
142 | |
143 | /// @reimp |
144 | virtual const char * format( int i ) const; |
145 | /// @reimp |
146 | virtual QByteArray encodedData( const char* mime ) const; |
147 | |
148 | protected: |
149 | /** |
150 | * @deprecated Use a K3URLDrag constructor with a KUrl::List |
151 | */ |
152 | K3URLDrag( const Q3StrList & urls, const QMap<QString,QString>& metaData, |
153 | QWidget * dragSource ); |
154 | |
155 | private: |
156 | void init(const KUrl::List &urls); |
157 | |
158 | Q3StrList m_urls; |
159 | QMap<QString,QString> m_metaData; |
160 | K3URLDragPrivate* d; |
161 | }; |
162 | |
163 | #endif |
164 | |
165 | |