source: trunk/src/gui/kernel/qclipboard.cpp@ 284

Last change on this file since 284 was 95, checked in by Dmitry A. Kuminov, 16 years ago

gui: Added OS/2 stubs for platform-specific parts of all key GUI classes. Non-key classes are temporarily disabled with QT_NO_ defines.

File size: 19.3 KB
Line 
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
54QT_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
155QClipboard::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*/
171QClipboard::~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