1/* This file is part of the KDE libraries
2 Copyright (C) 2000-2005 David Faure <faure@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef KIO_PASTE_H
20#define KIO_PASTE_H
21
22#include <kio/kio_export.h>
23#include <QtCore/QString>
24#include <kurl.h>
25class QWidget;
26class QMimeSource;
27
28namespace KIO {
29 class Job;
30 class CopyJob;
31
32 /**
33 * Pastes the content of the clipboard to the given destination URL.
34 * URLs are treated separately (performing a file copy)
35 * from other data (which is saved into a file after asking the user
36 * to choose a filename and the preferred data format)
37 *
38 * @param destURL the URL to receive the data
39 * @param widget parent widget to use for dialogs
40 * @param move true to move the data, false to copy -- now ignored and handled automatically
41 * @return the job that handles the operation
42 * @see pasteData()
43 */
44 KIO_EXPORT Job *pasteClipboard( const KUrl& destURL, QWidget* widget, bool move = false );
45
46 /**
47 * Pastes the given @p data to the given destination URL.
48 * NOTE: This method is blocking (uses NetAccess for saving the data).
49 * Please consider using pasteDataAsync instead.
50 *
51 * @param destURL the URL of the directory where the data will be pasted.
52 * The filename to use in that directory is prompted by this method.
53 * @param data the data to copy
54 * @param widget parent widget to use for dialogs
55 * @see pasteClipboard()
56 *
57 * This method is a candidate for disappearing in KDE5, email faure at kde.org if you
58 * are using it in your application, then I'll reconsider.
59 */
60 KIO_EXPORT void pasteData( const KUrl& destURL, const QByteArray& data, QWidget* widget );
61
62
63 /**
64 * Pastes the given @p data to the given destination URL.
65 * Note that this method requires the caller to have chosen the QByteArray
66 * to paste before hand, unlike pasteClipboard and pasteMimeSource.
67 *
68 * @param destURL the URL of the directory where the data will be pasted.
69 * The filename to use in that directory is prompted by this method.
70 * @param data the data to copy
71 * @param dialogText the text to show in the dialog
72 * @see pasteClipboard()
73 *
74 * This method is a candidate for disappearing in KDE5, email faure at kde.org if you
75 * are using it in your application, then I'll reconsider.
76 */
77 KIO_EXPORT CopyJob *pasteDataAsync( const KUrl& destURL, const QByteArray& data, QWidget *widget, const QString& dialogText = QString() );
78
79
80 /**
81 * Save the given mime @p data to the given destination URL
82 * after offering the user to choose a data format.
83 * This is the method used when handling drops (of anything else than URLs)
84 * onto dolphin and konqueror.
85 *
86 * @param data the QMimeData, usually from a QDropEvent
87 * @param destUrl the URL of the directory where the data will be pasted.
88 * The filename to use in that directory is prompted by this method.
89 * @param dialogText the text to show in the dialog
90 * @param widget parent widget to use for dialogs
91 * @param clipboard whether the QMimeData comes from QClipboard. If you
92 * use pasteClipboard for that case, you never have to worry about this parameter.
93 *
94 * @see pasteClipboard()
95 */
96 KIO_EXPORT Job* pasteMimeData(const QMimeData* data, const KUrl& destUrl,
97 const QString& dialogText, QWidget* widget);
98
99 /**
100 * @deprecated because it returns a CopyJob*, and this is better implemented
101 * without a copy job. Use pasteMimeData instead.
102 * Note that you'll have to tell the user in case of an error (no data to paste),
103 * while pasteMimeSource did that.
104 */
105 KIO_EXPORT_DEPRECATED CopyJob* pasteMimeSource( const QMimeData* data, const KUrl& destURL,
106 const QString& dialogText, QWidget* widget,
107 bool clipboard = false );
108
109
110 /**
111 * Returns true if pasteMimeSource finds any interesting format in @p data.
112 * You can use this method to enable/disable the paste action appropriately.
113 * @since 4.3
114 */
115 KIO_EXPORT bool canPasteMimeSource(const QMimeData* data);
116
117 /**
118 * Returns the text to use for the Paste action, when the application supports
119 * pasting files, urls, and clipboard data, using pasteClipboard().
120 * @return a string suitable for KAction::setText, or an empty string if pasting
121 * isn't possible right now.
122 */
123 KIO_EXPORT QString pasteActionText();
124}
125
126#endif
127