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
29class QMimeSource;
30
31class 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 */
46class KDE3SUPPORT_EXPORT K3URLDrag : public Q3UriDrag
47{
48public:
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
148protected:
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
155private:
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