You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdelibs/kdecore/kurldrag.h

166 lines
5.9 KiB

/* This file is part of the KDE project
Copyright (C) 2000 David Faure <faure@kde.org>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this program; see the file COPYING. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef __KURLDRAG_H
#define __KURLDRAG_H
#include <tqstringlist.h>
#include <tqdragobject.h>
#include <kurl.h>
#include "kdelibs_export.h"
class TQMimeSource;
class KURLDragPrivate;
/**
* This class is to be used instead of TQUriDrag when using KURL.
* The reason is: TQUriDrag (and the XDND/W3C standards) expect URLs to
* be encoded in UTF-8 (tqunicode), but KURL uses the current locale
* by default.
* The other reasons for using this class are:
* @li it exports text/plain (for dropping/pasting into lineedits, mails etc.)
* @li it has support for metadata, shipped as part of the dragobject
* This is important, for instance to set a correct HTTP referrer (some websites
* require it for downloading e.g. an image).
*
* To create a drag object, use the KURLDrag constructor.
* To handle drops, use TQUriDrag::canDecode() and KURLDrag::decode()
*/
class KDECORE_EXPORT KURLDrag : public TQUriDrag
{
public:
/**
* Constructs an object to drag the list of URLs in @p urls.
* The @p dragSource and @p name arguments are passed on to TQUriDrag,
* and the list of urls is converted to UTF-8 before being passed
* to TQUriDrag.
* @param urls the list of URLs
* @param dragSource the parent of the TQObject. Should be set when doing drag-n-drop,
* but should be 0 when copying to the clipboard
* @param name the name of the QObject
*/
KURLDrag( const KURL::List &urls, TQWidget* dragSource = 0, const char * name = 0 );
/**
* Constructs an object to drag the list of URLs in @p urls.
* This version also includes metadata.
* @param urls the list of URLs
* @param metaData a map containing meta data
* @param dragSource the parent of the TQObject. Should be set when doing drag-n-drop,
* but should be 0 when copying to the clipboard
* @param name the name of the QObject
* @see metaData()
*/
KURLDrag( const KURL::List &urls, const TQMap<TQString, TQString>& metaData,
TQWidget* dragSource = 0, const char * name = 0 );
virtual ~KURLDrag();
/**
* By default, KURLDrag also exports the URLs as plain text, for e.g. dropping onto a text editor.
* But in some cases this might not be wanted, e.g. if using the KURLDrag in a KMultipleDrag
* and another component of the multiple-drag provides better plain text data.
* In such a case, setExportAsText( false ) should be called.
* @since 3.4
*/
void setExportAsText( bool exp );
/**
* @deprecated Is equivalent with "new KURLDrag(urls, dragSource, name)".
*/
static KURLDrag * newDrag( const KURL::List &urls, TQWidget* dragSource = 0, const char * name = 0 ) KDE_DEPRECATED;
/**
* @deprecated Is equivalent with "new KURLDrag(urls, metaData, dragSource, name)".
*/
static KURLDrag * newDrag( const KURL::List &urls, const TQMap<TQString, TQString>& metaData,
TQWidget* dragSource = 0, const char * name = 0 ) KDE_DEPRECATED;
/**
* Meta-data to associate with those URLs.
* This is an alternative way of setting the metadata:
* either use the constructor to pass it all at once, or use
* drag->metaData()["key"] = data;
* @see KIO::TransferJob
*/
TQMap<TQString, TQString> &metaData() { return m_metaData; }
/**
* Convenience method that decodes the contents of @p e
* into a list of KURLs. Decoding will fail if at least one decoded value
* is not a valid KURL.
* @param e the mime source
* @param urls the list of urls will be written here
* @return true if successful, false otherwise
*/
static bool decode( const TQMimeSource *e, KURL::List &urls );
/**
* Convenience method that decodes the contents of @p e
* into a list of KURLs and a set of metadata. Decoding will fail if
* at least one decoded value is not a valid KURL.
* You should be using this one, if possible.
* @param e the mime source
* @param urls the list of urls will be written here
* @param metaData the metadata map will be written here
* @return true if successful, false otherwise
*/
static bool decode( const TQMimeSource *e, KURL::List &urls, TQMap<TQString,TQString>& metaData );
/**
* Converts a URL to a string representation suitable for dragging.
* @since 3.2
*/
static TQString urlToString(const KURL &url);
/**
* Converts a string used for dragging to a URL.
* @since 3.2
*/
static KURL stringToUrl(const TQCString &s);
#ifdef Q_WS_QWS
/**
* Convenience method that decodes the contents of @p e
* into a list of KURLs for Qt versions without a MIME clipboard.
* Decoding will fail if at least one value in the list is not a valid KURL.
*/
static bool decode( TQStringList const &e, KURL::List &uris );
#endif
/// @reimp
virtual const char * format( int i ) const;
/// @reimp
virtual TQByteArray encodedData( const char* mime ) const;
protected:
/**
* @deprecated Use a KURLDrag constructor with a KURL::List
*/
KURLDrag( const TQStrList & urls, const TQMap<TQString,TQString>& metaData,
TQWidget * dragSource, const char* name ) KDE_DEPRECATED;
private:
void init(const KURL::List &urls);
TQStrList m_urls;
TQMap<TQString,TQString> m_metaData;
KURLDragPrivate* d;
};
#endif