home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kurldrag.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  5.9 KB  |  166 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 2000 David Faure <faure@kde.org>
  3.  
  4.    This program is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License as published by the Free Software Foundation; either
  7.    version 2 of the License.
  8.  
  9.    This program is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this program; see the file COPYING.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef __KURLDRAG_H
  21. #define __KURLDRAG_H
  22.  
  23. #include <qstringlist.h>
  24. #include <qdragobject.h>
  25. #include <kurl.h>
  26. #include "kdelibs_export.h"
  27. class QMimeSource;
  28.  
  29. class KURLDragPrivate;
  30. /**
  31.  * This class is to be used instead of QUriDrag when using KURL.
  32.  * The reason is: QUriDrag (and the XDND/W3C standards) expect URLs to
  33.  * be encoded in UTF-8 (unicode), but KURL uses the current locale
  34.  * by default.
  35.  * The other reasons for using this class are:
  36.  * @li it exports text/plain (for dropping/pasting into lineedits, mails etc.)
  37.  * @li it has support for metadata, shipped as part of the dragobject
  38.  * This is important, for instance to set a correct HTTP referrer (some websites
  39.  * require it for downloading e.g. an image).
  40.  *
  41.  * To create a drag object, use the KURLDrag constructor.
  42.  * To handle drops, use QUriDrag::canDecode() and KURLDrag::decode()
  43.  */
  44. class KDECORE_EXPORT KURLDrag : public QUriDrag
  45. {
  46. public:
  47.   /**
  48.    * Constructs an object to drag the list of URLs in @p urls.
  49.    * The @p dragSource and @p name arguments are passed on to QUriDrag,
  50.    * and the list of urls is converted to UTF-8 before being passed
  51.    * to QUriDrag.
  52.    * @param urls the list of URLs
  53.    * @param dragSource the parent of the QObject. Should be set when doing drag-n-drop,
  54.    * but should be 0 when copying to the clipboard
  55.    * @param name the name of the QObject
  56.    */
  57.   KURLDrag( const KURL::List &urls, QWidget* dragSource = 0, const char * name = 0 );
  58.   /**
  59.    * Constructs an object to drag the list of URLs in @p urls.
  60.    * This version also includes metadata.
  61.    * @param urls the list of URLs
  62.    * @param metaData a map containing meta data
  63.    * @param dragSource the parent of the QObject. Should be set when doing drag-n-drop,
  64.    * but should be 0 when copying to the clipboard
  65.    * @param name the name of the QObject
  66.    * @see metaData()
  67.    */
  68.   KURLDrag( const KURL::List &urls, const QMap<QString, QString>& metaData,
  69.             QWidget* dragSource = 0, const char * name = 0 );
  70.  
  71.   virtual ~KURLDrag();
  72.  
  73.   /**
  74.    * By default, KURLDrag also exports the URLs as plain text, for e.g. dropping onto a text editor.
  75.    * But in some cases this might not be wanted, e.g. if using the KURLDrag in a KMultipleDrag
  76.    * and another component of the multiple-drag provides better plain text data.
  77.    * In such a case, setExportAsText( false ) should be called.
  78.    * @since 3.4
  79.    */
  80.   void setExportAsText( bool exp );
  81.  
  82.   /**
  83.    * @deprecated Is equivalent with "new KURLDrag(urls, dragSource, name)".
  84.    */
  85.   static KURLDrag * newDrag( const KURL::List &urls, QWidget* dragSource = 0, const char * name = 0 ) KDE_DEPRECATED;
  86.  
  87.   /**
  88.    * @deprecated Is equivalent with "new KURLDrag(urls, metaData, dragSource, name)".
  89.    */
  90.   static KURLDrag * newDrag( const KURL::List &urls, const QMap<QString, QString>& metaData,
  91.                              QWidget* dragSource = 0, const char * name = 0 ) KDE_DEPRECATED;
  92.  
  93.   /**
  94.    * Meta-data to associate with those URLs.
  95.    * This is an alternative way of setting the metadata:
  96.    * either use the constructor to pass it all at once, or use
  97.    * drag->metaData()["key"] = data;
  98.    * @see KIO::TransferJob
  99.    */
  100.   QMap<QString, QString> &metaData() { return m_metaData; }
  101.  
  102.   /**
  103.    * Convenience method that decodes the contents of @p e
  104.    * into a list of KURLs. Decoding will fail if at least one decoded value
  105.    * is not a valid KURL.
  106.    * @param e the mime source
  107.    * @param urls the list of urls will be written here
  108.    * @return true if successful, false otherwise
  109.    */
  110.   static bool decode( const QMimeSource *e, KURL::List &urls );
  111.  
  112.   /**
  113.    * Convenience method that decodes the contents of @p e
  114.    * into a list of KURLs and a set of metadata. Decoding will fail if
  115.    * at least one decoded value is not a valid KURL.
  116.    * You should be using this one, if possible.
  117.    * @param e the mime source
  118.    * @param urls the list of urls will be written here
  119.    * @param metaData the metadata map will be written here
  120.    * @return true if successful, false otherwise
  121.    */
  122.   static bool decode( const QMimeSource *e, KURL::List &urls, QMap<QString,QString>& metaData );
  123.  
  124.   /**
  125.    * Converts a URL to a string representation suitable for dragging.
  126.    * @since 3.2
  127.    */
  128.   static QString urlToString(const KURL &url);
  129.  
  130.   /**
  131.    * Converts a string used for dragging to a URL.
  132.    * @since 3.2
  133.    */
  134.   static KURL stringToUrl(const QCString &s);
  135.  
  136. #ifdef Q_WS_QWS
  137.   /**
  138.    * Convenience method that decodes the contents of @p e
  139.    * into a list of KURLs for Qt versions without a MIME clipboard.
  140.    * Decoding will fail if at least one value in the list is not a valid KURL.
  141.    */
  142.   static bool decode( QStringList const &e, KURL::List &uris );
  143. #endif
  144.  
  145.   /// @reimp
  146.   virtual const char * format( int i ) const;
  147.   /// @reimp
  148.   virtual QByteArray encodedData( const char* mime ) const;
  149.  
  150. protected:
  151.   /**
  152.    * @deprecated Use a KURLDrag constructor with a KURL::List
  153.    */
  154.   KURLDrag( const QStrList & urls, const QMap<QString,QString>& metaData,
  155.             QWidget * dragSource, const char* name ) KDE_DEPRECATED;
  156.  
  157. private:
  158.   void init(const KURL::List &urls);
  159.  
  160.   QStrList m_urls;
  161.   QMap<QString,QString> m_metaData;
  162.   KURLDragPrivate* d;
  163. };
  164.  
  165. #endif
  166.