1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    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 #include "qtextcodec.h"

    54 

    55 QT_BEGIN_NAMESPACE

    56 

    57 /*!

    58     \class QClipboard

    59     \brief The QClipboard class provides access to the window system clipboard.

    60 

    61     The clipboard offers a simple mechanism to copy and paste data

    62     between applications.

    63 

    64     QClipboard supports the same data types that QDrag does, and uses

    65     similar mechanisms. For advanced clipboard usage read \l{Drag and

    66     Drop}.

    67 

    68     There is a single QClipboard object in an application, accessible

    69     as QApplication::clipboard().

    70 

    71     Example:

    72     \snippet doc/src/snippets/code/src_gui_kernel_qclipboard.cpp 0

    73 

    74     QClipboard features some convenience functions to access common

    75     data types: setText() allows the exchange of Unicode text and

    76     setPixmap() and setImage() allows the exchange of QPixmaps and

    77     QImages between applications. The setMimeData() function is the

    78     ultimate in flexibility: it allows you to add any QMimeData into

    79     the clipboard. There are corresponding getters for each of these,

    80     e.g. text(), image() and pixmap(). You can clear the clipboard by

    81     calling clear().

    82 

    83     A typical example of the use of these functions follows:

    84 

    85     \snippet doc/src/snippets/droparea.cpp 0

    86 

    87     \section1 Notes for X11 Users

    88 

    89     \list

    90 

    91     \i The X11 Window System has the concept of a separate selection

    92     and clipboard.  When text is selected, it is immediately available

    93     as the global mouse selection.  The global mouse selection may

    94     later be copied to the clipboard.  By convention, the middle mouse

    95     button is used to paste the global mouse selection.

    96 

    97     \i X11 also has the concept of ownership; if you change the

    98     selection within a window, X11 will only notify the owner and the

    99     previous owner of the change, i.e. it will not notify all

   100     applications that the selection or clipboard data changed.

   101 

   102     \i Lastly, the X11 clipboard is event driven, i.e. the clipboard

   103     will not function properly if the event loop is not running.

   104     Similarly, it is recommended that the contents of the clipboard

   105     are stored or retrieved in direct response to user-input events,

   106     e.g. mouse button or key presses and releases.  You should not

   107     store or retrieve the clipboard contents in response to timer or

   108     non-user-input events.

   109 

   110     \endlist

   111 

   112     \section1 Notes for Mac OS X Users

   113 

   114     Mac OS X supports a separate find buffer that holds the current

   115     search string in Find operations. This find clipboard can be accessed

   116     by specifying the FindBuffer mode.

   117 

   118     \section1 Notes for Windows and Mac OS X Users

   119 

   120     \list

   121 

   122     \i Windows and Mac OS X do not support the global mouse

   123     selection; they only supports the global clipboard, i.e. they

   124     only add text to the clipboard when an explicit copy or cut is

   125     made.

   126 

   127     \i Windows and Mac OS X does not have the concept of ownership;

   128     the clipboard is a fully global resource so all applications are

   129     notified of changes.

   130 

   131     \endlist

   132 

   133     \sa QApplication

   134 */

   135 

   136 #ifndef Q_WS_X11

   137 // for X11 there is a separate implementation of a constructor.

   138 /*!

   139     \internal

   140 

   141     Constructs a clipboard object.

   142 

   143     Do not call this function.

   144 

   145     Call QApplication::clipboard() instead to get a pointer to the

   146     application's global clipboard object.

   147 

   148     There is only one clipboard in the window system, and creating

   149     more than one object to represent it is almost certainly an error.

   150 */

   151 

   152 QClipboard::QClipboard(QObject *parent)

   153     : QObject(*new QClipboardPrivate, parent)

   154 {

   155     // nothing

   156 }

   157 #endif

   158 

   159 #ifndef Q_WS_WIN32

   160 /*!

   161     \internal

   162 

   163     Destroys the clipboard.

   164 

   165     You should never delete the clipboard. QApplication will do this

   166     when the application terminates.

   167 */

   168 QClipboard::~QClipboard()

   169 {

   170 }

   171 #endif

   172 

   173 /*!

   174     \fn void QClipboard::changed(QClipboard::Mode mode)

   175     \since 4.2

   176 

   177     This signal is emitted when the data for the given clipboard \a

   178     mode is changed.

   179 

   180     \sa dataChanged(), selectionChanged(), findBufferChanged()

   181 */

   182 

   183 /*!

   184     \fn void QClipboard::dataChanged()

   185 

   186     This signal is emitted when the clipboard data is changed.

   187 

   188     On Mac OS X and with Qt version 4.3 or higher, clipboard

   189     changes made by other applications will only be detected

   190     when the application is activated.

   191 

   192     \sa findBufferChanged(), selectionChanged(), changed()

   193 */

   194 

   195 /*!

   196     \fn void QClipboard::selectionChanged()

   197 

   198     This signal is emitted when the selection is changed. This only

   199     applies to windowing systems that support selections, e.g. X11.

   200     Windows and Mac OS X don't support selections.

   201 

   202     \sa dataChanged(), findBufferChanged(), changed()

   203 */

   204 

   205 /*!

   206     \fn void QClipboard::findBufferChanged()

   207     \since 4.2

   208 

   209     This signal is emitted when the find buffer is changed. This only

   210     applies to Mac OS X.

   211 

   212     With Qt version 4.3 or higher, clipboard changes made by other

   213     applications will only be detected when the application is activated.

   214 

   215     \sa dataChanged(), selectionChanged(), changed()

   216 */

   217 

   218 

   219 /*! \enum QClipboard::Mode

   220     \keyword clipboard mode

   221 

   222     This enum type is used to control which part of the system clipboard is

   223     used by QClipboard::mimeData(), QClipboard::setMimeData() and related functions.

   224 

   225     \value Clipboard  indicates that data should be stored and retrieved from

   226     the global clipboard.

   227 

   228     \value Selection  indicates that data should be stored and retrieved from

   229     the global mouse selection. Support for \c Selection is provided only on 

   230     systems with a global mouse selection (e.g. X11).

   231 

   232     \value FindBuffer indicates that data should be stored and retrieved from

   233     the Find buffer. This mode is used for holding search strings on Mac OS X.

   234 

   235     \omitvalue LastMode

   236 

   237     \sa QClipboard::supportsSelection()

   238 */

   239 

   240 

   241 /*****************************************************************************

   242   QApplication member functions related to QClipboard.

   243  *****************************************************************************/

   244 

   245 // text handling is done directly in qclipboard_qws, for now

   246 

   247 /*!

   248     \fn bool QClipboard::event(QEvent *e)

   249     \reimp

   250 */

   251 

   252 /*!

   253     \overload

   254 

   255     Returns the clipboard text in subtype \a subtype, or an empty string

   256     if the clipboard does not contain any text. If \a subtype is null,

   257     any subtype is acceptable, and \a subtype is set to the chosen

   258     subtype.

   259 

   260     The \a mode argument is used to control which part of the system

   261     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   262     text is retrieved from the global clipboard.  If \a mode is

   263     QClipboard::Selection, the text is retrieved from the global

   264     mouse selection.

   265 

   266     Common values for \a subtype are "plain" and "html".

   267 

   268     Note that calling this function repeatedly, for instance from a

   269     key event handler, may be slow. In such cases, you should use the

   270     \c dataChanged() signal instead.

   271 

   272     \sa setText(), mimeData()

   273 */

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

   275 {

   276     const QMimeData *const data = mimeData(mode);

   277     if (!data)

   278         return QString();

   279 

   280     const QStringList formats = data->formats();

   281     if (subtype.isEmpty()) {

   282         if (formats.contains(QLatin1String("text/plain")))

   283             subtype = QLatin1String("plain");

   284         else {

   285             for (int i = 0; i < formats.size(); ++i)

   286                 if (formats.at(i).startsWith(QLatin1String("text/"))) {

   287                     subtype = formats.at(i).mid(5);

   288                     break;

   289                 }

   290             if (subtype.isEmpty())

   291                 return QString();

   292         }

   293     } else if (!formats.contains(QLatin1String("text/") + subtype)) {

   294         return QString();

   295     }

   296 

   297     const QByteArray rawData = data->data(QLatin1String("text/") + subtype);

   298 

   299     QTextCodec* codec = QTextCodec::codecForMib(106); // utf-8 is default

   300     if (subtype == QLatin1String("html"))

   301         codec = QTextCodec::codecForHtml(rawData, codec);

   302     else

   303         codec = QTextCodec::codecForUtfText(rawData, codec);

   304     return codec->toUnicode(rawData);

   305 }

   306 

   307 /*!

   308     Returns the clipboard text as plain text, or an empty string if the

   309     clipboard does not contain any text.

   310 

   311     The \a mode argument is used to control which part of the system

   312     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   313     text is retrieved from the global clipboard.  If \a mode is

   314     QClipboard::Selection, the text is retrieved from the global

   315     mouse selection. If \a mode is QClipboard::FindBuffer, the

   316     text is retrieved from the search string buffer.

   317 

   318     \sa setText(), mimeData()

   319 */

   320 QString QClipboard::text(Mode mode) const

   321 {

   322     const QMimeData *data = mimeData(mode);

   323     return data ? data->text() : QString();

   324 }

   325 

   326 /*!

   327     Copies \a text into the clipboard as plain text.

   328 

   329     The \a mode argument is used to control which part of the system

   330     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   331     text is stored in the global clipboard.  If \a mode is

   332     QClipboard::Selection, the text is stored in the global

   333     mouse selection. If \a mode is QClipboard::FindBuffer, the

   334     text is stored in the search string buffer.

   335 

   336     \sa text(), setMimeData()

   337 */

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

   339 {

   340     QMimeData *data = new QMimeData;

   341     data->setText(text);

   342     setMimeData(data, mode);

   343 }

   344 

   345 /*!

   346     Returns the clipboard image, or returns a null image if the

   347     clipboard does not contain an image or if it contains an image in

   348     an unsupported image format.

   349 

   350     The \a mode argument is used to control which part of the system

   351     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   352     image is retrieved from the global clipboard.  If \a mode is

   353     QClipboard::Selection, the image is retrieved from the global

   354     mouse selection. 

   355 

   356     \sa setImage() pixmap() mimeData(), QImage::isNull()

   357 */

   358 QImage QClipboard::image(Mode mode) const

   359 {

   360     const QMimeData *data = mimeData(mode);

   361     if (!data)

   362         return QImage();

   363     return qvariant_cast<QImage>(data->imageData());

   364 }

   365 

   366 /*!

   367     Copies the \a image into the clipboard.

   368 

   369     The \a mode argument is used to control which part of the system

   370     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   371     image is stored in the global clipboard.  If \a mode is

   372     QClipboard::Selection, the data is stored in the global

   373     mouse selection.

   374 

   375     This is shorthand for:

   376 

   377     \snippet doc/src/snippets/code/src_gui_kernel_qclipboard.cpp 1

   378 

   379     \sa image(), setPixmap() setMimeData()

   380 */

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

   382 {

   383     QMimeData *data = new QMimeData;

   384     data->setImageData(image);

   385     setMimeData(data, mode);

   386 }

   387 

   388 /*!

   389     Returns the clipboard pixmap, or null if the clipboard does not

   390     contain a pixmap. Note that this can lose information. For

   391     example, if the image is 24-bit and the display is 8-bit, the

   392     result is converted to 8 bits, and if the image has an alpha

   393     channel, the result just has a mask.

   394 

   395     The \a mode argument is used to control which part of the system

   396     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   397     pixmap is retrieved from the global clipboard.  If \a mode is

   398     QClipboard::Selection, the pixmap is retrieved from the global

   399     mouse selection.

   400 

   401     \sa setPixmap() image() mimeData() QPixmap::convertFromImage()

   402 */

   403 QPixmap QClipboard::pixmap(Mode mode) const

   404 {

   405     const QMimeData *data = mimeData(mode);

   406     return data ? qvariant_cast<QPixmap>(data->imageData()) : QPixmap();

   407 }

   408 

   409 /*!

   410     Copies \a pixmap into the clipboard. Note that this is slower

   411     than setImage() because it needs to convert the QPixmap to a

   412     QImage first.

   413 

   414     The \a mode argument is used to control which part of the system

   415     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   416     pixmap is stored in the global clipboard.  If \a mode is

   417     QClipboard::Selection, the pixmap is stored in the global

   418     mouse selection.

   419 

   420     \sa pixmap() setImage() setMimeData()

   421 */

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

   423 {

   424     QMimeData *data = new QMimeData;

   425     data->setImageData(pixmap);

   426     setMimeData(data, mode);

   427 }

   428 

   429 

   430 /*!

   431     \fn QMimeData *QClipboard::mimeData(Mode mode) const

   432 

   433     Returns a reference to a QMimeData representation of the current

   434     clipboard data.

   435 

   436     The \a mode argument is used to control which part of the system

   437     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   438     data is retrieved from the global clipboard.  If \a mode is

   439     QClipboard::Selection, the data is retrieved from the global

   440     mouse selection. If \a mode is QClipboard::FindBuffer, the

   441     data is retrieved from the search string buffer.

   442 

   443     The text(), image(), and pixmap() functions are simpler

   444     wrappers for retrieving text, image, and pixmap data.

   445 

   446     \sa setMimeData()

   447 */

   448 

   449 /*!

   450     \fn void QClipboard::setMimeData(QMimeData *src, Mode mode)

   451 

   452     Sets the clipboard data to \a src. Ownership of the data is

   453     transferred to the clipboard. If you want to remove the data

   454     either call clear() or call setMimeData() again with new data.

   455 

   456     The \a mode argument is used to control which part of the system

   457     clipboard is used.  If \a mode is QClipboard::Clipboard, the

   458     data is stored in the global clipboard.  If \a mode is

   459     QClipboard::Selection, the data is stored in the global

   460     mouse selection. If \a mode is QClipboard::FindBuffer, the

   461     data is stored in the search string buffer.

   462 

   463     The setText(), setImage() and setPixmap() functions are simpler

   464     wrappers for setting text, image and pixmap data respectively.

   465 

   466     \sa mimeData()

   467 */

   468 

   469 /*! 

   470     \fn void QClipboard::clear(Mode mode)

   471     Clear the clipboard contents.

   472 

   473     The \a mode argument is used to control which part of the system

   474     clipboard is used.  If \a mode is QClipboard::Clipboard, this

   475     function clears the global clipboard contents.  If \a mode is

   476     QClipboard::Selection, this function clears the global mouse

   477     selection contents. If \a mode is QClipboard::FindBuffer, this 

   478     function clears the search string buffer.

   479 

   480     \sa QClipboard::Mode, supportsSelection()

   481 */

   482 

   483 #ifdef QT3_SUPPORT

   484 /*!

   485     \fn QMimeSource *QClipboard::data(Mode mode) const

   486     \compat

   487 

   488     Use mimeData() instead.

   489 */

   490 QMimeSource *QClipboard::data(Mode mode) const

   491 {

   492     Q_D(const QClipboard);

   493 

   494     if (supportsMode(mode) == false)

   495         return 0;

   496 

   497     if (d->compat_data[mode])

   498         return d->compat_data[mode];

   499 

   500     d->wrapper[mode]->data = mimeData(mode);

   501     return d->wrapper[mode];

   502 }

   503 

   504 

   505 /*!

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

   507     \compat

   508 

   509     Use setMimeData() instead.

   510 */

   511 void QClipboard::setData(QMimeSource *source, Mode mode)

   512 {

   513     Q_D(QClipboard);

   514 

   515     if (supportsMode(mode) == false)

   516         return;

   517 

   518     d->compat_data[mode] = source;

   519     setMimeData(new QMimeSourceWrapper(d, mode), mode);

   520 }

   521 #endif // QT3_SUPPORT

   522 

   523 /*!

   524     Returns true if the clipboard supports mouse selection; otherwise

   525     returns false.

   526 */

   527 bool QClipboard::supportsSelection() const

   528 {

   529     return supportsMode(Selection);

   530 }

   531 

   532 /*!

   533     Returns true if the clipboard supports a separate search buffer; otherwise

   534     returns false.

   535 */

   536 bool QClipboard::supportsFindBuffer() const

   537 {

   538     return supportsMode(FindBuffer);

   539 }

   540 

   541 /*!

   542     Returns true if this clipboard object owns the clipboard data;

   543     otherwise returns false.

   544 */

   545 bool QClipboard::ownsClipboard() const

   546 {

   547     return ownsMode(Clipboard);

   548 }

   549 

   550 /*!

   551     Returns true if this clipboard object owns the mouse selection

   552     data; otherwise returns false.

   553 */

   554 bool QClipboard::ownsSelection() const

   555 {

   556     return ownsMode(Selection);

   557 }

   558 

   559 /*!

   560     \since 4.2

   561 

   562     Returns true if this clipboard object owns the find buffer data;

   563     otherwise returns false.

   564 */

   565 bool QClipboard::ownsFindBuffer() const

   566 {

   567     return ownsMode(FindBuffer);

   568 }

   569 

   570 /*! 

   571     \internal

   572     \fn bool QClipboard::supportsMode(Mode mode) const;

   573     Returns true if the clipboard supports the clipboard mode speacified by \a mode;

   574     otherwise returns false.

   575 */

   576 

   577 /*! 

   578     \internal

   579     \fn bool QClipboard::ownsMode(Mode mode) const;

   580     Returns true if the clipboard supports the clipboard data speacified by \a mode;

   581     otherwise returns false.

   582 */

   583 

   584 /*! 

   585     \internal

   586     Emits the appropriate changed signal for \a mode.

   587 */

   588 void QClipboard::emitChanged(Mode mode)

   589 {

   590     switch (mode) {

   591         case Clipboard:

   592             emit dataChanged();

   593         break;

   594         case Selection:

   595             emit selectionChanged();

   596         break;

   597         case FindBuffer:

   598             emit findBufferChanged();

   599         break;

   600         default:

   601         break;

   602     }

   603     emit changed(mode);

   604 }

   605 

   606 const char* QMimeDataWrapper::format(int n) const

   607 {

   608     if (formats.isEmpty()) {

   609         QStringList fmts = data->formats();

   610         for (int i = 0; i < fmts.size(); ++i)

   611             formats.append(fmts.at(i).toLatin1());

   612     }

   613     if (n < 0 || n >= formats.size())

   614         return 0;

   615     return formats.at(n).data();

   616 }

   617 

   618 QByteArray QMimeDataWrapper::encodedData(const char *format) const

   619 {

   620     if (QLatin1String(format) != QLatin1String("application/x-qt-image")){

   621         return data->data(QLatin1String(format));

   622     } else{

   623         QVariant variant = data->imageData();

   624         QImage img = qVariantValue<QImage>(variant);

   625         QByteArray ba;

   626         QBuffer buffer(&ba);

   627         buffer.open(QIODevice::WriteOnly);

   628         img.save(&buffer, "PNG");

   629         return ba;

   630     }

   631 }

   632 

   633 QVariant QMimeSourceWrapper::retrieveData(const QString &mimetype, QVariant::Type) const

   634 {

   635     return source->encodedData(mimetype.toLatin1());

   636 }

   637 

   638 bool QMimeSourceWrapper::hasFormat(const QString &mimetype) const

   639 {

   640     return source->provides(mimetype.toLatin1());

   641 }

   642 

   643 QStringList QMimeSourceWrapper::formats() const

   644 {

   645     QStringList fmts;

   646     int i = 0;

   647     const char *fmt;

   648     while ((fmt = source->format(i))) {

   649         fmts.append(QLatin1String(fmt));

   650         ++i;

   651     }

   652     return fmts;

   653 }

   654 

   655 #endif // QT_NO_CLIPBOARD

   656 

   657 QT_END_NAMESPACE