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> |
25 | class QWidget; |
26 | class QMimeSource; |
27 | |
28 | namespace 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 | |