kurl.h

Go to the documentation of this file.

// -*- c-basic-offset: 2 -*-
/* This file is part of the KDE libraries
 *  Copyright (C) 1999 Torben Weis <weis@kde.org>
 *  Copyright (C) 2005-2006 David Faure <faure@kde.org>
 *
 *  This library 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, or (at your option) any later version.
 *
 *  This library 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 library; see the file COPYING.LIB.  If not, write to
 *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *  Boston, MA 02110-1301, USA.
 */

#ifndef kurl_h
#define kurl_h

#include <kdecore_export.h>

#include <QtCore/QVariant>
#include <QtCore/QUrl>
#include <QtCore/QMap>

class QStringList;
class QMimeData;

class KUrlPrivate;

// maybe we should encapsulate QUrl instead of inheriting from it.
// this would even allow us to inherit from KUri instead.
// and this way hacks like setPath() would be less ugly, and we could avoid
// half KDE code using setScheme() and the other half using setProtocol(), etc.
// (DF)

class KDECORE_EXPORT KUrl : public QUrl // krazy:exclude=dpointer,qclasses (krazy can't deal with embedded classes)
{
public:
  typedef QMap<QString, QString> MetaDataMap;
  enum MimeDataFlags { DefaultMimeDataFlags = 0, NoTextExport = 1 };

  enum AdjustPathOption
  {
    RemoveTrailingSlash,

    LeaveTrailingSlash,

    AddTrailingSlash
  };

  class KDECORE_EXPORT List : public QList<KUrl> //krazy:exclude=dpointer (just some convenience methods)
  {
  public:
      List() { }
      List(const KUrl &url);
      List(const QStringList &list);
      List(const QList<KUrl> &list);
      QStringList toStringList() const;

      QStringList toStringList(KUrl::AdjustPathOption trailing) const;

      operator QVariant() const;

      void populateMimeData( QMimeData* mimeData,
                             const KUrl::MetaDataMap& metaData = MetaDataMap(),
                             MimeDataFlags flags = DefaultMimeDataFlags ) const;

      void populateMimeData(const KUrl::List& mostLocalUrls,
                            QMimeData* mimeData,
                            const KUrl::MetaDataMap& metaData = MetaDataMap(),
                            MimeDataFlags flags = DefaultMimeDataFlags) const;

      static bool canDecode( const QMimeData *mimeData );

      static QStringList mimeDataTypes();

      static KUrl::List fromMimeData( const QMimeData *mimeData, KUrl::MetaDataMap* metaData = 0 );

      enum DecodeOptions {
        PreferLocalUrls,
        PreferKdeUrls
      };

      static KUrl::List fromMimeData( const QMimeData *mimeData,
                                      DecodeOptions decodeOptions, // TODO KDE5: = PreferKdeUrls, and merge with above
                                      KUrl::MetaDataMap* metaData = 0 );

  };
  KUrl();

  ~KUrl();

  KUrl( const QString& urlOrPath );
  explicit KUrl( const char * urlOrPath );
  explicit KUrl( const QByteArray& urlOrPath );

  KUrl( const KUrl& u );
  KUrl( const QUrl &u ); //krazy:exclude=qclasses
  KUrl( const KUrl& _baseurl, const QString& _rel_url );

  QString protocol() const;

  void setProtocol( const QString& proto );

  QString user() const;

  void setUser( const QString& user );

  bool hasUser() const;

  QString pass() const;

  void setPass( const QString& pass );

  bool hasPass() const;

  bool hasHost() const;

  QString path( AdjustPathOption trailing = LeaveTrailingSlash ) const;

  QString toLocalFile( AdjustPathOption trailing = LeaveTrailingSlash ) const;

  void setPath( const QString& path );

  bool hasPath() const;

  enum CleanPathOption
  {
    SimplifyDirSeparators = 0x00,

    KeepDirSeparators = 0x01
  };

  Q_DECLARE_FLAGS(CleanPathOptions,CleanPathOption)

  
  void cleanPath(const CleanPathOption& options = SimplifyDirSeparators);


  void adjustPath(AdjustPathOption trailing);

  void setEncodedPathAndQuery( const QString& _txt );

#if 0

  void setEncodedPath(const QString& _txt );
#endif

  enum EncodedPathAndQueryOption
  {
    PermitEmptyPath=0x00,
    AvoidEmptyPath=0x01
  };
  Q_DECLARE_FLAGS( EncodedPathAndQueryOptions, EncodedPathAndQueryOption)

  
  QString encodedPathAndQuery( AdjustPathOption trailing = LeaveTrailingSlash, const EncodedPathAndQueryOptions &options = PermitEmptyPath ) const;

  void setQuery( const QString& query );

  QString query() const;

  QString ref() const;

  void setRef( const QString& fragment );

  bool hasRef() const;

  QString htmlRef() const;

  QString encodedHtmlRef() const;

  void setHTMLRef( const QString& _ref );

  bool hasHTMLRef() const;

  bool isLocalFile() const;

  void setFileEncoding(const QString &encoding);

  QString fileEncoding() const;

  bool hasSubUrl() const;

  void addPath( const QString& txt );

  enum QueryItemsOption { CaseInsensitiveKeys = 1 };
  Q_DECLARE_FLAGS(QueryItemsOptions,QueryItemsOption)

  
  QMap< QString, QString > queryItems( const QueryItemsOptions& options = 0 ) const;
  // #### TODO port the above queryItems to look more like QUrl's
  //using QUrl::queryItems; // temporary

  QString queryItem(const QString &item) const;

  void addQueryItem( const QString& _item, const QString& _value );


  void setFileName( const QString&_txt );

  enum DirectoryOption
  {
    ObeyTrailingSlash = 0x02,
    AppendTrailingSlash = 0x04,
    IgnoreTrailingSlash = 0x01

  };
  Q_DECLARE_FLAGS(DirectoryOptions,DirectoryOption)


  
  QString fileName( const DirectoryOptions& options = IgnoreTrailingSlash ) const;

  QString directory( const DirectoryOptions& options = IgnoreTrailingSlash ) const;

  void setDirectory(const QString &dir);

  bool cd( const QString& _dir );

  QString url( AdjustPathOption trailing = LeaveTrailingSlash ) const;

  QString prettyUrl( AdjustPathOption trailing = LeaveTrailingSlash ) const;

  QString pathOrUrl() const;
  QString pathOrUrl(AdjustPathOption trailing) const; // KDE5: merge with above. Rename to toUrlOrLocalFile?

  QString toMimeDataString() const;

  KUrl upUrl( ) const;

  KUrl& operator=( const KUrl& _u );

  // Define those, since the constructors are explicit
  KUrl& operator=( const char * _url ) { *this = KUrl(_url); return *this; }
  KUrl& operator=( const QByteArray& _url ) { *this = KUrl(_url); return *this; }
  KUrl& operator=( const QString& _url ) { *this = KUrl(_url); return *this; }

  bool operator==( const KUrl& _u ) const;
  bool operator==( const QString& _u ) const;
  bool operator!=( const KUrl& _u ) const { return !( *this == _u ); }
  bool operator!=( const QString& _u ) const { return !( *this == _u ); }

  operator QVariant() const;

#ifndef KDE_NO_DEPRECATED
  KDE_DEPRECATED bool cmp( const KUrl &u, bool ignore_trailing = false ) const;
#endif


  enum EqualsOption
  {
    CompareWithoutTrailingSlash = 0x01,
    CompareWithoutFragment = 0x02,
    AllowEmptyPath = 0x04
  };
  Q_DECLARE_FLAGS(EqualsOptions,EqualsOption)

  
  bool equals( const KUrl &u, const EqualsOptions& options=0 ) const;

  bool isParentOf( const KUrl& u ) const;
    // (this overload of the QUrl method allows to use the implicit KUrl constructors)
    // but also the equality test

  static List split( const QString& _url );

  static List split( const KUrl& _url );

  static KUrl join( const List& _list );

  static KUrl fromPath( const QString& text );

#ifndef KDE_NO_DEPRECATED
  static KDE_DEPRECATED KUrl fromPathOrUrl( const QString& text );
#endif

  static KUrl fromMimeDataByteArray( const QByteArray& str );

  void populateMimeData( QMimeData* mimeData,
                         const MetaDataMap& metaData = MetaDataMap(),
                         MimeDataFlags flags = DefaultMimeDataFlags ) const;

#ifndef KDE_NO_DEPRECATED
  static KDE_DEPRECATED QString encode_string(const QString &str) {
    return QString::fromLatin1( QUrl::toPercentEncoding( str ).constData() ); //krazy:exclude=qclasses
  }
#endif

#ifndef KDE_NO_DEPRECATED
  static KDE_DEPRECATED QString encode_string_no_slash(const QString &str) {
      return QString::fromLatin1( QUrl::toPercentEncoding( str, "/" ).constData() ); //krazy:exclude=qclasses
  }
#endif

#ifndef KDE_NO_DEPRECATED
  static KDE_DEPRECATED QString decode_string(const QString &str) {
      return QUrl::fromPercentEncoding( str.toLatin1() ); //krazy:exclude=qclasses
  }
#endif


  static bool isRelativeUrl(const QString &_url);

  static QString relativeUrl(const KUrl &base_url, const KUrl &url);

  static QString relativePath(const QString &base_dir, const QString &path, bool *isParent=0);

private:
  void _setQuery( const QString& query );
  void _setEncodedUrl(const QByteArray& url);
  QString toString() const; // forbidden, use url(), prettyUrl(), or pathOrUrl() instead.
  operator QString() const; // forbidden, use url(), prettyUrl(), or pathOrUrl() instead.
private:
  KUrlPrivate* const d; // Don't ever use this, it would break clear() (which is in QUrl)
};

Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::EncodedPathAndQueryOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::CleanPathOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::QueryItemsOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::EqualsOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::DirectoryOptions)

Q_DECLARE_METATYPE(KUrl)
Q_DECLARE_METATYPE(KUrl::List)

#ifndef KDE_NO_DEPRECATED
KDECORE_EXPORT_DEPRECATED bool urlcmp( const QString& _url1, const QString& _url2 ); // KDE5: remove, KUrl::equals is better API
#endif

#ifndef KDE_NO_DEPRECATED
KDECORE_EXPORT_DEPRECATED bool urlcmp( const QString& _url1, const QString& _url2, const KUrl::EqualsOptions& options ); // KDE5: remove, KUrl::equals is better API
#endif

KDECORE_EXPORT uint qHash(const KUrl& kurl);

#endif