1 | /****************************************************************************
|
---|
2 | **
|
---|
3 | ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
|
---|
4 | ** Contact: Qt Software Information ([email protected])
|
---|
5 | **
|
---|
6 | ** This file is part of the QtGui module of the Qt Toolkit.
|
---|
7 | **
|
---|
8 | ** $QT_BEGIN_LICENSE:LGPL$
|
---|
9 | ** Commercial Usage
|
---|
10 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
11 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
12 | ** Software or, alternatively, in accordance with the terms contained in
|
---|
13 | ** a written agreement between you and Nokia.
|
---|
14 | **
|
---|
15 | ** GNU Lesser General Public License Usage
|
---|
16 | ** Alternatively, this file may be used under the terms of the GNU Lesser
|
---|
17 | ** General Public License version 2.1 as published by the Free Software
|
---|
18 | ** Foundation and appearing in the file LICENSE.LGPL included in the
|
---|
19 | ** packaging of this file. Please review the following information to
|
---|
20 | ** ensure the GNU Lesser General Public License version 2.1 requirements
|
---|
21 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
|
---|
22 | **
|
---|
23 | ** In addition, as a special exception, Nokia gives you certain
|
---|
24 | ** additional rights. These rights are described in the Nokia Qt LGPL
|
---|
25 | ** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
|
---|
26 | ** package.
|
---|
27 | **
|
---|
28 | ** GNU General Public License Usage
|
---|
29 | ** Alternatively, this file may be used under the terms of the GNU
|
---|
30 | ** General Public License version 3.0 as published by the Free Software
|
---|
31 | ** Foundation and appearing in the file LICENSE.GPL included in the
|
---|
32 | ** packaging of this file. Please review the following information to
|
---|
33 | ** ensure the GNU General Public License version 3.0 requirements will be
|
---|
34 | ** met: http://www.gnu.org/copyleft/gpl.html.
|
---|
35 | **
|
---|
36 | ** If you are unsure which license is appropriate for your use, please
|
---|
37 | ** contact the sales department at [email protected].
|
---|
38 | ** $QT_END_LICENSE$
|
---|
39 | **
|
---|
40 | ****************************************************************************/
|
---|
41 |
|
---|
42 | #include "qclipboard.h"
|
---|
43 |
|
---|
44 | #ifndef QT_NO_CLIPBOARD
|
---|
45 |
|
---|
46 | #include "qapplication.h"
|
---|
47 | #include "qapplication_p.h"
|
---|
48 | #include "qpixmap.h"
|
---|
49 | #include "qclipboard_p.h"
|
---|
50 | #include "qvariant.h"
|
---|
51 | #include "qbuffer.h"
|
---|
52 | #include "qimage.h"
|
---|
53 |
|
---|
54 | QT_BEGIN_NAMESPACE
|
---|
55 |
|
---|
56 | /*!
|
---|
57 | \class QClipboard
|
---|
58 | \brief The QClipboard class provides access to the window system clipboard.
|
---|
59 |
|
---|
60 | \ingroup io
|
---|
61 | \ingroup environment
|
---|
62 | \mainclass
|
---|
63 |
|
---|
64 | The clipboard offers a simple mechanism to copy and paste data
|
---|
65 | between applications.
|
---|
66 |
|
---|
67 | QClipboard supports the same data types that QDrag does, and uses
|
---|
68 | similar mechanisms. For advanced clipboard usage read \l{Drag and
|
---|
69 | Drop}.
|
---|
70 |
|
---|
71 | There is a single QClipboard object in an application, accessible
|
---|
72 | as QApplication::clipboard().
|
---|
73 |
|
---|
74 | Example:
|
---|
75 | \snippet doc/src/snippets/code/src_gui_kernel_qclipboard.cpp 0
|
---|
76 |
|
---|
77 | QClipboard features some convenience functions to access common
|
---|
78 | data types: setText() allows the exchange of Unicode text and
|
---|
79 | setPixmap() and setImage() allows the exchange of QPixmaps and
|
---|
80 | QImages between applications. The setMimeData() function is the
|
---|
81 | ultimate in flexibility: it allows you to add any QMimeData into
|
---|
82 | the clipboard. There are corresponding getters for each of these,
|
---|
83 | e.g. text(), image() and pixmap(). You can clear the clipboard by
|
---|
84 | calling clear().
|
---|
85 |
|
---|
86 | A typical example of the use of these functions follows:
|
---|
87 |
|
---|
88 | \snippet doc/src/snippets/droparea.cpp 0
|
---|
89 |
|
---|
90 | \section1 Notes for X11 Users
|
---|
91 |
|
---|
92 | \list
|
---|
93 |
|
---|
94 | \i The X11 Window System has the concept of a separate selection
|
---|
95 | and clipboard. When text is selected, it is immediately available
|
---|
96 | as the global mouse selection. The global mouse selection may
|
---|
97 | later be copied to the clipboard. By convention, the middle mouse
|
---|
98 | button is used to paste the global mouse selection.
|
---|
99 |
|
---|
100 | \i X11 also has the concept of ownership; if you change the
|
---|
101 | selection within a window, X11 will only notify the owner and the
|
---|
102 | previous owner of the change, i.e. it will not notify all
|
---|
103 | applications that the selection or clipboard data changed.
|
---|
104 |
|
---|
105 | \i Lastly, the X11 clipboard is event driven, i.e. the clipboard
|
---|
106 | will not function properly if the event loop is not running.
|
---|
107 | Similarly, it is recommended that the contents of the clipboard
|
---|
108 | are stored or retrieved in direct response to user-input events,
|
---|
109 | e.g. mouse button or key presses and releases. You should not
|
---|
110 | store or retrieve the clipboard contents in response to timer or
|
---|
111 | non-user-input events.
|
---|
112 |
|
---|
113 | \endlist
|
---|
114 |
|
---|
115 | \section1 Notes for Mac OS X Users
|
---|
116 |
|
---|
117 | Mac OS X supports a separate find buffer that holds the current
|
---|
118 | search string in Find operations. This find clipboard can be accessed
|
---|
119 | by specifying the FindBuffer mode.
|
---|
120 |
|
---|
121 | \section1 Notes for Windows and Mac OS X Users
|
---|
122 |
|
---|
123 | \list
|
---|
124 |
|
---|
125 | \i Windows and Mac OS X do not support the global mouse
|
---|
126 | selection; they only supports the global clipboard, i.e. they
|
---|
127 | only add text to the clipboard when an explicit copy or cut is
|
---|
128 | made.
|
---|
129 |
|
---|
130 | \i Windows and Mac OS X does not have the concept of ownership;
|
---|
131 | the clipboard is a fully global resource so all applications are
|
---|
132 | notified of changes.
|
---|
133 |
|
---|
134 | \endlist
|
---|
135 |
|
---|
136 | \sa QApplication
|
---|
137 | */
|
---|
138 |
|
---|
139 | #ifndef Q_WS_X11
|
---|
140 | // for X11 there is a separate implementation of a constructor.
|
---|
141 | /*!
|
---|
142 | \internal
|
---|
143 |
|
---|
144 | Constructs a clipboard object.
|
---|
145 |
|
---|
146 | Do not call this function.
|
---|
147 |
|
---|
148 | Call QApplication::clipboard() instead to get a pointer to the
|
---|
149 | application's global clipboard object.
|
---|
150 |
|
---|
151 | There is only one clipboard in the window system, and creating
|
---|
152 | more than one object to represent it is almost certainly an error.
|
---|
153 | */
|
---|
154 |
|
---|
155 | QClipboard::QClipboard(QObject *parent)
|
---|
156 | : QObject(*new QClipboardPrivate, parent)
|
---|
157 | {
|
---|
158 | // nothing
|
---|
159 | }
|
---|
160 | #endif
|
---|
161 |
|
---|
162 | #if !defined(Q_WS_WIN32) && !defined(Q_WS_PM)
|
---|
163 | /*!
|
---|
164 | \internal
|
---|
165 |
|
---|
166 | Destroys the clipboard.
|
---|
167 |
|
---|
168 | You should never delete the clipboard. QApplication will do this
|
---|
169 | when the application terminates.
|
---|
170 | */
|
---|
171 | QClipboard::~QClipboard()
|
---|
172 | {
|
---|
173 | }
|
---|
174 | #endif
|
---|
175 |
|
---|
176 | /*!
|
---|
177 | \fn void QClipboard::changed(QClipboard::Mode mode)
|
---|
178 | \since 4.2
|
---|
179 |
|
---|
180 | This signal is emitted when the data for the given clipboard \a
|
---|
181 | mode is changed.
|
---|
182 |
|
---|
183 | \sa dataChanged(), selectionChanged(), findBufferChanged()
|
---|
184 | */
|
---|
185 |
|
---|
186 | /*!
|
---|
187 | \fn void QClipboard::dataChanged()
|
---|
188 |
|
---|
189 | This signal is emitted when the clipboard data is changed.
|
---|
190 |
|
---|
191 | On Mac OS X and with Qt version 4.3 or higher, clipboard
|
---|
192 | changes made by other applications will only be detected
|
---|
193 | when the application is activated.
|
---|
194 |
|
---|
195 | \sa findBufferChanged(), selectionChanged(), changed()
|
---|
196 | */
|
---|
197 |
|
---|
198 | /*!
|
---|
199 | \fn void QClipboard::selectionChanged()
|
---|
200 |
|
---|
201 | This signal is emitted when the selection is changed. This only
|
---|
202 | applies to windowing systems that support selections, e.g. X11.
|
---|
203 | Windows and Mac OS X don't support selections.
|
---|
204 |
|
---|
205 | \sa dataChanged(), findBufferChanged(), changed()
|
---|
206 | */
|
---|
207 |
|
---|
208 | /*!
|
---|
209 | \fn void QClipboard::findBufferChanged()
|
---|
210 | \since 4.2
|
---|
211 |
|
---|
212 | This signal is emitted when the find buffer is changed. This only
|
---|
213 | applies to Mac OS X.
|
---|
214 |
|
---|
215 | With Qt version 4.3 or higher, clipboard changes made by other
|
---|
216 | applications will only be detected when the application is activated.
|
---|
217 |
|
---|
218 | \sa dataChanged(), selectionChanged(), changed()
|
---|
219 | */
|
---|
220 |
|
---|
221 |
|
---|
222 | /*! \enum QClipboard::Mode
|
---|
223 | \keyword clipboard mode
|
---|
224 |
|
---|
225 | This enum type is used to control which part of the system clipboard is
|
---|
226 | used by QClipboard::mimeData(), QClipboard::setMimeData() and related functions.
|
---|
227 |
|
---|
228 | \value Clipboard indicates that data should be stored and retrieved from
|
---|
229 | the global clipboard.
|
---|
230 |
|
---|
231 | \value Selection indicates that data should be stored and retrieved from
|
---|
232 | the global mouse selection. Support for \c Selection is provided only on
|
---|
233 | systems with a global mouse selection (e.g. X11).
|
---|
234 |
|
---|
235 | \value FindBuffer indicates that data should be stored and retrieved from
|
---|
236 | the Find buffer. This mode is used for holding search strings on Mac OS X.
|
---|
237 |
|
---|
238 | \omitvalue LastMode
|
---|
239 |
|
---|
|
---|