QClipboard(3qt)

1QClipboard(3qt)                                                QClipboard(3qt)
2
3
4

NAME

6       QClipboard - Access to the window system clipboard
7

SYNOPSIS

9       #include <qclipboard.h>
10
11       Inherits QObject.
12
13   Public Members
14       enum Mode { Clipboard, Selection }
15       void clear ( Mode mode )
16       void clear ()
17       bool supportsSelection () const
18       bool ownsSelection () const
19       bool ownsClipboard () const
20       void setSelectionMode ( bool enable )  (obsolete)
21       bool selectionModeEnabled () const  (obsolete)
22       QString text ( Mode mode ) const
23       QString text ( QCString & subtype, Mode mode ) const
24       void setText ( const QString & text, Mode mode )
25       QMimeSource * data ( Mode mode ) const
26       void setData ( QMimeSource * src, Mode mode )
27       QImage image ( Mode mode ) const
28       QPixmap pixmap ( Mode mode ) const
29       void setImage ( const QImage & image, Mode mode )
30       void setPixmap ( const QPixmap & pixmap, Mode mode )
31       QString text () const
32       QString text ( QCString & subtype ) const
33       void setText ( const QString & text )
34       QMimeSource * data () const
35       void setData ( QMimeSource * src )
36       QImage image () const
37       QPixmap pixmap () const
38       void setImage ( const QImage & image )
39       void setPixmap ( const QPixmap & pixmap )
40
41   Signals
42       void selectionChanged ()
43       void dataChanged ()
44

DESCRIPTION

46       The QClipboard class provides access to the window system clipboard.
47
48       The clipboard offers a simple mechanism to copy and paste data between
49       applications.
50
51       QClipboard supports the same data types that QDragObject does, and uses
52       similar mechanisms. For advanced clipboard usage read the drag-and-drop
53       documentation.
54
55       There is a single QClipboard object in an application, and you can
56       access it using QApplication::clipboard().
57
58       Example:
59
60           QClipboard *cb = QApplication::clipboard();
61           // Copy text from the clipboard (paste)
62           QString text = cb->text(QClipboard::Clipboard);
63           if ( !text.isNull() )
64               qDebug( "The clipboard contains: " + text );
65           // Copy text into the clipboard
66           cb->setText( "This text can be pasted by other programs",
67                        QClipboard::Clipboard );
68
69       QClipboard features some convenience functions to access common data
70       types: setText() allows the exchange of Unicode text and setPixmap()
71       and setImage() allows the exchange of QPixmaps and QImages between
72       applications. The setData() function is the ultimate in flexibility: it
73       allows you to add any QMimeSource into the clipboard. There are
74       corresponding getters for each of these, e.g. text(), image() and
75       pixmap().
76
77       You can clear the clipboard by calling clear().
78

Platform Specific Information

80       <h4> X11 </h4>
81
82       The X11 Window System has the concept of a separate selection and
83       clipboard. When text is selected, it is immediately available as the
84       global mouse selection. The global mouse selection may later be copied
85       to the clipboard. By convention, the middle mouse button is used to
86       paste the global mouse selection.
87
88       X11 also has the concept of ownership; if you change the selection
89       within a window, X11 will only notify the owner and the previous owner
90       of the change, i.e. it will not notify all applications that the
91       selection or clipboard data changed.
92
93       Lastly, the X11 clipboard is event driven, i.e. the clipboard will not
94       function properly if the event loop is not running. Similarly, it is
95       recommended that the contents of the clipboard are stored or retrieved
96       in direct response to user-input events, e.g. mouse button or key
97       presses and releases. You should not store or retrieve the clipboard
98       contents in response to timer or non-user-input events.
99
100       <h4> Windows </h4>
101
102       Microsoft Windows does not support the global mouse selection; it only
103       supports the global clipboard, e.g. Windows only adds text to the
104       clipboard when an explicit copy or cut is made.
105
106       Windows does not have the concept of ownership; the clipboard is a
107       fully global resource so all applications are notified of changes.
108
109       See the multiclip example in the Qt Designer examples directory for an
110       example of a multiplatform clipboard application that also demonstrates
111       selection handling.
112
113       See also Environment Classes and Input/Output and Networking.
114
115   Member Type Documentation

QClipboard::Mode

117       This enum type is used to control which part of the system clipboard is
118       used by QClipboard::data(), QClipboard::setData() and related
119       functions.
120
121       QClipboard::Clipboard - indicates that data should be stored and
122       retrieved from the global clipboard.
123
124       QClipboard::Selection - indicates that data should be stored and
125       retrieved from the global mouse selection.
126
127       Note: Support for Selection is provided only on systems with a global
128       mouse selection (e.g. X11).
129
130       See also QClipboard::supportsSelection().
131

MEMBER FUNCTION DOCUMENTATION

void QClipboard::clear ( Mode mode )

134       Clear the clipboard contents.
135
136       The mode argument is used to control which part of the system clipboard
137       is used. If mode is QClipboard::Clipboard, this function clears the the
138       global clipboard contents. If mode is QClipboard::Selection, this
139       function clears the global mouse selection contents.
140
141       See also QClipboard::Mode and supportsSelection().
142

void QClipboard::clear ()

144       This is an overloaded member function, provided for convenience. It
145       behaves essentially like the above function.
146
147       This function uses the QClipboard::clear() function which takes a
148       QClipboard::Mode argument. The value of the mode argument is determined
149       by the return value of selectionModeEnabled(). If
150       selectionModeEnabled() returns TRUE, the mode argument is
151       QClipboard::Selection, otherwise the mode argument is
152       QClipboard::Clipboard.
153

QMimeSource * QClipboard::data ( Mode mode ) const

155       Returns a reference to a QMimeSource representation of the current
156       clipboard data.
157
158       The mode argument is used to control which part of the system clipboard
159       is used. If mode is QClipboard::Clipboard, the data is retrieved from
160       the global clipboard. If mode is QClipboard::Selection, the data is
161       retrieved from the global mouse selection.
162
163       See also setData().
164

QMimeSource * QClipboard::data () const

166       This is an overloaded member function, provided for convenience. It
167       behaves essentially like the above function.
168
169       This function uses the QClipboard::data() function which takes a
170       QClipboard::Mode argument. The value of the mode argument is determined
171       by the return value of selectionModeEnabled(). If
172       selectionModeEnabled() returns TRUE, the mode argument is
173       QClipboard::Selection, otherwise the mode argument is
174       QClipboard::Clipboard.
175

void QClipboard::dataChanged () [signal]

177       This signal is emitted when the clipboard data is changed.
178

QImage QClipboard::image ( Mode mode ) const

180       Returns the clipboard image, or returns a null image if the clipboard
181       does not contain an image or if it contains an image in an unsupported
182       image format.
183
184       The mode argument is used to control which part of the system clipboard
185       is used. If mode is QClipboard::Clipboard, the image is retrieved from
186       the global clipboard. If mode is QClipboard::Selection, the image is
187       retrieved from the global mouse selection.
188
189       See also setImage(), pixmap(), data(), and QImage::isNull().
190

QImage QClipboard::image () const

192       This is an overloaded member function, provided for convenience. It
193       behaves essentially like the above function.
194
195       This function uses the QClipboard::image() function which takes a
196       QClipboard::Mode argument. The value of the mode argument is determined
197       by the return value of selectionModeEnabled(). If
198       selectionModeEnabled() returns TRUE, the mode argument is
199       QClipboard::Selection, otherwise the mode argument is
200       QClipboard::Clipboard.
201

bool QClipboard::ownsClipboard () const

203       Returns TRUE if this clipboard object owns the clipboard data;
204       otherwise returns FALSE.
205

bool QClipboard::ownsSelection () const

207       Returns TRUE if this clipboard object owns the mouse selection data;
208       otherwise returns FALSE.
209

QPixmap QClipboard::pixmap ( Mode mode ) const

211       Returns the clipboard pixmap, or null if the clipboard does not contain
212       a pixmap. Note that this can lose information. For example, if the
213       image is 24-bit and the display is 8-bit, the result is converted to 8
214       bits, and if the image has an alpha channel, the result just has a
215       mask.
216
217       The mode argument is used to control which part of the system clipboard
218       is used. If mode is QClipboard::Clipboard, the pixmap is retrieved from
219       the global clipboard. If mode is QClipboard::Selection, the pixmap is
220       retrieved from the global mouse selection.
221
222       See also setPixmap(), image(), data(), and QPixmap::convertFromImage().
223

QPixmap QClipboard::pixmap () const

225       This is an overloaded member function, provided for convenience. It
226       behaves essentially like the above function.
227
228       This function uses the QClipboard::pixmap() function which takes a
229       QClipboard::Mode argument. The value of the mode argument is determined
230       by the return value of selectionModeEnabled(). If
231       selectionModeEnabled() returns TRUE, the mode argument is
232       QClipboard::Selection, otherwise the mode argument is
233       QClipboard::Clipboard.
234

void QClipboard::selectionChanged () [signal]

236       This signal is emitted when the selection is changed. This only applies
237       to windowing systems that support selections, e.g. X11. Windows doesn't
238       support selections.
239

bool QClipboard::selectionModeEnabled () const

241       This function is obsolete. It is provided to keep old source working.
242       We strongly advise against using it in new code.
243
244       Use the QClipboard::data(), QClipboard::setData() and related functions
245       which take a QClipboard::Mode argument.
246
247       Returns the selection mode.
248
249       See also setSelectionMode() and supportsSelection().
250

void QClipboard::setData ( QMimeSource * src, Mode mode )

252       Sets the clipboard data to src. Ownership of the data is transferred to
253       the clipboard. If you want to remove the data either call clear() or
254       call setData() again with new data.
255
256       The mode argument is used to control which part of the system clipboard
257       is used. If mode is QClipboard::Clipboard, the data is retrieved from
258       the global clipboard. If mode is QClipboard::Selection, the data is
259       retrieved from the global mouse selection.
260
261       The QDragObject subclasses are reasonable objects to put into the
262       clipboard (but do not try to call QDragObject::drag() on the same
263       object). Any QDragObject placed in the clipboard should have a parent
264       of 0. Do not put QDragMoveEvent or QDropEvent subclasses in the
265       clipboard, as they do not belong to the event handler which receives
266       them.
267
268       The setText(), setImage() and setPixmap() functions are simpler
269       wrappers for setting text, image and pixmap data respectively.
270
271       See also data().
272

void QClipboard::setData ( QMimeSource * src )

274       This is an overloaded member function, provided for convenience. It
275       behaves essentially like the above function.
276
277       This function uses the QClipboard::setData() function which takes a
278       QClipboard::Mode argument. The value of the mode argument is determined
279       by the return value of selectionModeEnabled(). If
280       selectionModeEnabled() returns TRUE, the mode argument is
281       QClipboard::Selection, otherwise the mode argument is
282       QClipboard::Clipboard.
283

void QClipboard::setImage ( const QImage & image, Mode mode )

285       Copies image into the clipboard.
286
287       The mode argument is used to control which part of the system clipboard
288       is used. If mode is QClipboard::Clipboard, the image is stored in the
289       global clipboard. If mode is QClipboard::Selection, the data is stored
290       in the global mouse selection.
291
292       This is shorthand for:
293
294               setData( new QImageDrag(image), mode )
295
296       See also image(), setPixmap(), and setData().
297

void QClipboard::setImage ( const QImage & image )

299       This is an overloaded member function, provided for convenience. It
300       behaves essentially like the above function.
301
302       This function uses the QClipboard::setImage() function which takes a
303       QClipboard::Mode argument. The value of the mode argument is determined
304       by the return value of selectionModeEnabled(). If
305       selectionModeEnabled() returns TRUE, the mode argument is
306       QClipboard::Selection, otherwise the mode argument is
307       QClipboard::Clipboard.
308

void QClipboard::setPixmap ( const QPixmap & pixmap, Mode mode )

310       Copies pixmap into the clipboard. Note that this is slower than
311       setImage() because it needs to convert the QPixmap to a QImage first.
312
313       The mode argument is used to control which part of the system clipboard
314       is used. If mode is QClipboard::Clipboard, the pixmap is stored in the
315       global clipboard. If mode is QClipboard::Selection, the pixmap is
316       stored in the global mouse selection.
317
318       See also pixmap(), setImage(), and setData().
319

void QClipboard::setPixmap ( const QPixmap & pixmap )

321       This is an overloaded member function, provided for convenience. It
322       behaves essentially like the above function.
323
324       This function uses the QClipboard::setPixmap() function which takes a
325       QClipboard::Mode argument. The value of the mode argument is determined
326       by the return value of selectionModeEnabled(). If
327       selectionModeEnabled() returns TRUE, the mode argument is
328       QClipboard::Selection, otherwise the mode argument is
329       QClipboard::Clipboard.
330

void QClipboard::setSelectionMode ( bool enable )

332       This function is obsolete. It is provided to keep old source working.
333       We strongly advise against using it in new code.
334
335       Use the QClipboard::data(), QClipboard::setData() and related functions
336       which take a QClipboard::Mode argument.
337
338       Sets the clipboard selection mode. If enable is TRUE, then subsequent
339       calls to QClipboard::setData() and other functions which put data into
340       the clipboard will put the data into the mouse selection, otherwise the
341       data will be put into the clipboard.
342
343       See also supportsSelection() and selectionModeEnabled().
344

void QClipboard::setText ( const QString & text, Mode mode )

346       Copies text into the clipboard as plain text.
347
348       The mode argument is used to control which part of the system clipboard
349       is used. If mode is QClipboard::Clipboard, the text is stored in the
350       global clipboard. If mode is QClipboard::Selection, the text is stored
351       in the global mouse selection.
352
353       See also text() and setData().
354
355       Example: regexptester/regexptester.cpp.
356

void QClipboard::setText ( const QString & text )

358       This is an overloaded member function, provided for convenience. It
359       behaves essentially like the above function.
360
361       This function uses the QClipboard::setText() function which takes a
362       QClipboard::Mode argument. The value of the mode argument is determined
363       by the return value of selectionModeEnabled(). If
364       selectionModeEnabled() returns TRUE, the mode argument is
365       QClipboard::Selection, otherwise the mode argument is
366       QClipboard::Clipboard.
367

bool QClipboard::supportsSelection () const

369       Returns TRUE if the clipboard supports mouse selection; otherwise
370       returns FALSE.
371
372       Example: regexptester/regexptester.cpp.
373

QString QClipboard::text ( Mode mode ) const

375       Returns the clipboard text as plain text, or a null string if the
376       clipboard does not contain any text.
377
378       The mode argument is used to control which part of the system clipboard
379       is used. If mode is QClipboard::Clipboard, the text is retrieved from
380       the global clipboard. If mode is QClipboard::Selection, the text is
381       retrieved from the global mouse selection.
382
383       See also setText(), data(), and QString::operator!().
384

QString QClipboard::text ( QCString & subtype, Mode mode ) const

386       This is an overloaded member function, provided for convenience. It
387       behaves essentially like the above function.
388
389       Returns the clipboard text in subtype subtype, or a null string if the
390       clipboard does not contain any text. If subtype is null, any subtype is
391       acceptable, and subtype is set to the chosen subtype.
392
393       The mode argument is used to control which part of the system clipboard
394       is used. If mode is QClipboard::Clipboard, the text is retrieved from
395       the global clipboard. If mode is QClipboard::Selection, the text is
396       retrieved from the global mouse selection.
397
398       Common values for subtype are "plain" and "html".
399
400       See also setText(), data(), and QString::operator!().
401

QString QClipboard::text () const

403       This is an overloaded member function, provided for convenience. It
404       behaves essentially like the above function.
405
406       This function uses the QClipboard::text() function which takes a
407       QClipboard::Mode argument. The value of the mode argument is determined
408       by the return value of selectionModeEnabled(). If
409       selectionModeEnabled() returns TRUE, the mode argument is
410       QClipboard::Selection, otherwise the mode argument is
411       QClipboard::Clipboard.
412

QString QClipboard::text ( QCString & subtype ) const

414       This is an overloaded member function, provided for convenience. It
415       behaves essentially like the above function.
416
417       Returns the clipboard text in subtype subtype, or a null string if the
418       clipboard does not contain any text. This function uses the
419       QClipboard::text() function which takes a QClipboard::Mode argument.
420       The value of the mode argument is determined by the return value of
421       selectionModeEnabled(). If selectionModeEnabled() returns TRUE, the
422       mode argument is QClipboard::Selection, otherwise the mode argument is
423       QClipboard::Clipboard.
424
425

COPYRIGHT

431       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
432       license file included in the distribution for a complete license
433       statement.
434

AUTHOR

436       Generated automatically from the source code.
437

BUGS

439       If you find a bug in Qt, please report it as described in
440       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
441       help you. Thank you.
442
443       The definitive Qt documentation is provided in HTML format; it is
444       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
445       web browser. This man page is provided as a convenience for those users
446       who prefer man pages, although this format is not officially supported
447       by Trolltech.
448
449       If you find errors in this manual page, please report them to qt-
450       bugs@trolltech.com.  Please include the name of the manual page
451       (qclipboard.3qt) and the Qt version (3.3.8).
452
453
454
455Trolltech AS                    2 February 2007                QClipboard(3qt)