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

     2 **

     3 ** Copyright (C) 2010 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 #ifndef QT_NO_TEXTCODEC

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

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

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

   303     else

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

   305     return codec->toUnicode(rawData);

   306 #else //QT_NO_TEXTCODEC

   307     return rawData;

   308 #endif //QT_NO_TEXTCODEC

   309 }

   310 

   311 /*!

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

   313     clipboard does not contain any text.

   314 

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

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

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

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

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

   320     text is retrieved from the search string buffer.

   321 

   322     \sa setText(), mimeData()

   323 */

   324 QString QClipboard::text(Mode mode) const

   325 {

   326     const QMimeData *data = mimeData(mode);

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

   328 }

   329 

   330 /*!

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

   332 

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

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

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

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

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

   338     text is stored in the search string buffer.

   339 

   340     \sa text(), setMimeData()

   341 */

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

   343 {

   344     QMimeData *data = new QMimeData;

   345     data->setText(text);

   346     setMimeData(data, mode);

   347 }

   348 

   349 /*!

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

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

   352     an unsupported image format.

   353 

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

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

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

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

   358     mouse selection. 

   359 

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

   361 */

   362 QImage QClipboard::image(Mode mode) const

   363 {

   364     const QMimeData *data = mimeData(mode);

   365     if (!data)

   366         return QImage();

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

   368 }

   369 

   370 /*!

   371     Copies the \a image into the clipboard.

   372 

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

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

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

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

   377     mouse selection.

   378 

   379     This is shorthand for:

   380 

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

   382 

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

   384 */

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

   386 {

   387     QMimeData *data = new QMimeData;

   388     data->setImageData(image);

   389     setMimeData(data, mode);

   390 }

   391 

   392 /*!

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

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

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

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

   397     channel, the result just has a mask.

   398 

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

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

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

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

   403     mouse selection.

   404 

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

   406 */

   407 QPixmap QClipboard::pixmap(Mode mode) const

   408 {

   409     const QMimeData *data = mimeData(mode);

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

   411 }

   412 

   413 /*!

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

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

   416     QImage first.

   417 

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

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

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

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

   422     mouse selection.

   423 

   424     \sa pixmap() setImage() setMimeData()

   425 */

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

   427 {

   428     QMimeData *data = new QMimeData;

   429     data->setImageData(pixmap);

   430     setMimeData(data, mode);

   431 }

   432 

   433 

   434 /*!

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

   436 

   437     Returns a reference to a QMimeData representation of the current

   438     clipboard data.

   439 

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

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

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

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

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

   445     data is retrieved from the search string buffer.

   446 

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

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

   449 

   450     \sa setMimeData()

   451 */

   452 

   453 /*!

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

   455 

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

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

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

   459 

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

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

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

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

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

   465     data is stored in the search string buffer.

   466 

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

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

   469 

   470     \sa mimeData()

   471 */

   472 

   473 /*! 

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

   475     Clear the clipboard contents.

   476 

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

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

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

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

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

   482     function clears the search string buffer.

   483 

   484     \sa QClipboard::Mode, supportsSelection()

   485 */

   486 

   487 #ifdef QT3_SUPPORT

   488 /*!

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

   490     \compat

   491 

   492     Use mimeData() instead.

   493 */

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

   495 {

   496     Q_D(const QClipboard);

   497 

   498     if (supportsMode(mode) == false)

   499         return 0;

   500 

   501     if (d->compat_data[mode])

   502         return d->compat_data[mode];

   503 

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

   505     return d->wrapper[mode];

   506 }

   507 

   508 

   509 /*!

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

   511     \compat

   512 

   513     Use setMimeData() instead.

   514 */

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

   516 {

   517     Q_D(QClipboard);

   518 

   519     if (supportsMode(mode) == false)

   520         return;

   521 

   522     d->compat_data[mode] = source;

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

   524 }

   525 #endif // QT3_SUPPORT

   526 

   527 /*!

   528     Returns true if the clipboard supports mouse selection; otherwise

   529     returns false.

   530 */

   531 bool QClipboard::supportsSelection() const

   532 {

   533     return supportsMode(Selection);

   534 }

   535 

   536 /*!

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

   538     returns false.

   539 */

   540 bool QClipboard::supportsFindBuffer() const

   541 {

   542     return supportsMode(FindBuffer);

   543 }

   544 

   545 /*!

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

   547     otherwise returns false.

   548 */

   549 bool QClipboard::ownsClipboard() const

   550 {

   551     return ownsMode(Clipboard);

   552 }

   553 

   554 /*!

   555     Returns true if this clipboard object owns the mouse selection

   556     data; otherwise returns false.

   557 */

   558 bool QClipboard::ownsSelection() const

   559 {

   560     return ownsMode(Selection);

   561 }

   562 

   563 /*!

   564     \since 4.2

   565 

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

   567     otherwise returns false.

   568 */

   569 bool QClipboard::ownsFindBuffer() const

   570 {

   571     return ownsMode(FindBuffer);

   572 }

   573 

   574 /*! 

   575     \internal

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

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

   578     otherwise returns false.

   579 */

   580 

   581 /*! 

   582     \internal

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

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

   585     otherwise returns false.

   586 */

   587 

   588 /*! 

   589     \internal

   590     Emits the appropriate changed signal for \a mode.

   591 */

   592 void QClipboard::emitChanged(Mode mode)

   593 {

   594     switch (mode) {

   595         case Clipboard:

   596             emit dataChanged();

   597         break;

   598         case Selection:

   599             emit selectionChanged();

   600         break;

   601         case FindBuffer:

   602             emit findBufferChanged();

   603         break;

   604         default:

   605         break;

   606     }

   607     emit changed(mode);

   608 }

   609 

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

   611 {

   612     if (formats.isEmpty()) {

   613         QStringList fmts = data->formats();

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

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

   616     }

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

   618         return 0;

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

   620 }

   621 

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

   623 {

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

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

   626     } else{

   627         QVariant variant = data->imageData();

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

   629         QByteArray ba;

   630         QBuffer buffer(&ba);

   631         buffer.open(QIODevice::WriteOnly);

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

   633         return ba;

   634     }

   635 }

   636 

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

   638 {

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

   640 }

   641 

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

   643 {

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

   645 }

   646 

   647 QStringList QMimeSourceWrapper::formats() const

   648 {

   649     QStringList fmts;

   650     int i = 0;

   651     const char *fmt;

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

   653         fmts.append(QLatin1String(fmt));

   654         ++i;

   655     }

   656     return fmts;

   657 }

   658 

   659 #endif // QT_NO_CLIPBOARD

   660 

   661 QT_END_NAMESPACE