KUrl

#include <KUrl>

Inheritance diagram for KUrl:

Classes

class  List
 

Public Types

enum  AdjustPathOption { RemoveTrailingSlash, LeaveTrailingSlash, AddTrailingSlash }
 
enum  CleanPathOption { SimplifyDirSeparators = 0x00, KeepDirSeparators = 0x01 }
 
typedef QFlags< CleanPathOptionCleanPathOptions
 
enum  DirectoryOption { ObeyTrailingSlash = 0x02, AppendTrailingSlash = 0x04, IgnoreTrailingSlash = 0x01 }
 
typedef QFlags< DirectoryOptionDirectoryOptions
 
enum  EncodedPathAndQueryOption { PermitEmptyPath = 0x00, AvoidEmptyPath = 0x01 }
 
typedef QFlags< EncodedPathAndQueryOptionEncodedPathAndQueryOptions
 
enum  EqualsOption { CompareWithoutTrailingSlash = 0x01, CompareWithoutFragment = 0x02, AllowEmptyPath = 0x04 }
 
typedef QFlags< EqualsOptionEqualsOptions
 
typedef QMap< QString, QStringMetaDataMap
 
enum  MimeDataFlags { DefaultMimeDataFlags = 0, NoTextExport = 1 }
 
enum  QueryItemsOption { CaseInsensitiveKeys = 1 }
 
typedef QFlags< QueryItemsOptionQueryItemsOptions
 
- Public Types inherited from QUrl
enum  ComponentFormattingOption
 
enum  ParsingMode
 
enum  UrlFormattingOption
 
enum  UserInputResolutionOption
 

Public Member Functions

 KUrl ()
 
 KUrl (const QString &urlOrPath)
 
 KUrl (const char *urlOrPath)
 
 KUrl (const QByteArray &urlOrPath)
 
 KUrl (const KUrl &u)
 
 KUrl (const QUrl &u)
 
 KUrl (const KUrl &_baseurl, const QString &_rel_url)
 
 ~KUrl ()
 
void addPath (const QString &txt)
 
void addQueryItem (const QString &_item, const QString &_value)
 
void adjustPath (AdjustPathOption trailing)
 
bool cd (const QString &_dir)
 
void cleanPath (const CleanPathOption &options=SimplifyDirSeparators)
 
bool cmp (const KUrl &u, bool ignore_trailing=false) const
 
QString directory (const DirectoryOptions &options=IgnoreTrailingSlash) const
 
QString encodedHtmlRef () const
 
QString encodedPathAndQuery (AdjustPathOption trailing=LeaveTrailingSlash, const EncodedPathAndQueryOptions &options=PermitEmptyPath) const
 
bool equals (const KUrl &u, const EqualsOptions &options={}) const
 
QString fileEncoding () const
 
QString fileName (const DirectoryOptions &options=IgnoreTrailingSlash) const
 
bool hasHost () const
 
bool hasHTMLRef () const
 
bool hasPass () const
 
bool hasPath () const
 
bool hasRef () const
 
bool hasSubUrl () const
 
bool hasUser () const
 
QString htmlRef () const
 
bool isLocalFile () const
 
bool isParentOf (const KUrl &child) const
 
 operator QVariant () const
 
bool operator!= (const KUrl &_u) const
 
bool operator!= (const QString &_u) const
 
KUrloperator= (const KUrl &_u)
 
KUrloperator= (const char *_url)
 
KUrloperator= (const QByteArray &_url)
 
KUrloperator= (const QString &_url)
 
bool operator== (const KUrl &_u) const
 
bool operator== (const QString &_u) const
 
QString pass () const
 
QString path (AdjustPathOption trailing=LeaveTrailingSlash) const
 
QString pathOrUrl (AdjustPathOption trailing=LeaveTrailingSlash) const
 
void populateMimeData (QMimeData *mimeData, const MetaDataMap &metaData=MetaDataMap(), MimeDataFlags flags=DefaultMimeDataFlags) const
 
QString prettyUrl (AdjustPathOption trailing=LeaveTrailingSlash) const
 
QString protocol () const
 
QString query () const
 
QString queryItem (const QString &item) const
 
QMap< QString, QStringqueryItems (const QueryItemsOptions &options={}) const
 
QString ref () const
 
void setDirectory (const QString &dir)
 
void setEncodedPathAndQuery (const QString &_txt)
 
void setFileEncoding (const QString &encoding)
 
void setFileName (const QString &_txt)
 
void setHTMLRef (const QString &ref)
 
void setPass (const QString &pass)
 
void setPath (const QString &path)
 
void setProtocol (const QString &proto)
 
void setQuery (const QString &query)
 
void setRef (const QString &fragment)
 
void setUser (const QString &user)
 
QString toLocalFile (AdjustPathOption trailing=LeaveTrailingSlash) const
 
QString toMimeDataString () const
 
KUrl upUrl () const
 
QString url (AdjustPathOption trailing=LeaveTrailingSlash) const
 
QString user () const
 
- Public Member Functions inherited from QUrl
 QUrl (const QUrl &other)
 
 QUrl (const QString &url, QUrl::ParsingMode parsingMode)
 
 QUrl (QUrl &&other)
 
void addEncodedQueryItem (const QByteArray &key, const QByteArray &value)
 
void addQueryItem (const QString &key, const QString &value)
 
QUrl adjusted (QUrl::FormattingOptions options) const const
 
QList< QByteArrayallEncodedQueryItemValues (const QByteArray &key) const const
 
QStringList allQueryItemValues (const QString &key) const const
 
QString authority (QUrl::ComponentFormattingOptions options) const const
 
void clear ()
 
QByteArray encodedFragment () const const
 
QByteArray encodedHost () const const
 
QByteArray encodedPassword () const const
 
QByteArray encodedPath () const const
 
QByteArray encodedQuery () const const
 
QList< QPair< QByteArray, QByteArray > > encodedQueryItems () const const
 
QByteArray encodedQueryItemValue (const QByteArray &key) const const
 
QByteArray encodedUserName () const const
 
QString errorString () const const
 
QString fileName (QUrl::ComponentFormattingOptions options) const const
 
QString fragment (QUrl::ComponentFormattingOptions options) const const
 
bool hasEncodedQueryItem (const QByteArray &key) const const
 
bool hasFragment () const const
 
bool hasQuery () const const
 
bool hasQueryItem (const QString &key) const const
 
QString host (QUrl::ComponentFormattingOptions options) const const
 
bool isEmpty () const const
 
bool isLocalFile () const const
 
bool isParentOf (const QUrl &childUrl) const const
 
bool isRelative () const const
 
bool isValid () const const
 
bool matches (const QUrl &url, QUrl::FormattingOptions options) const const
 
bool operator!= (const QUrl &url) const const
 
QDataStreamoperator<< (QDataStream &out, const QUrl &url)
 
QUrloperator= (const QString &url)
 
QUrloperator= (const QUrl &url)
 
QUrloperator= (QUrl &&other)
 
bool operator== (const QUrl &url) const const
 
QDataStreamoperator>> (QDataStream &in, QUrl &url)
 
QString password (QUrl::ComponentFormattingOptions options) const const
 
QString path (QUrl::ComponentFormattingOptions options) const const
 
int port (int defaultPort) const const
 
 QT_NO_URL_CAST_FROM_STRING QT_NO_URL_CAST_FROM_STRING
 
QString query (QUrl::ComponentFormattingOptions options) const const
 
QList< QPair< QString, QString > > queryItems () const const
 
QString queryItemValue (const QString &key) const const
 
void removeAllEncodedQueryItems (const QByteArray &key)
 
void removeAllQueryItems (const QString &key)
 
void removeEncodedQueryItem (const QByteArray &key)
 
void removeQueryItem (const QString &key)
 
QUrl resolved (const QUrl &relative) const const
 
QString scheme () const const
 
void setAuthority (const QString &authority, QUrl::ParsingMode mode)
 
void setEncodedFragment (const QByteArray &fragment)
 
void setEncodedHost (const QByteArray &host)
 
void setEncodedPassword (const QByteArray &password)
 
void setEncodedPath (const QByteArray &path)
 
void setEncodedQuery (const QByteArray &query)
 
void setEncodedQueryItems (const QList< QPair< QByteArray, QByteArray > > &query)
 
void setEncodedUrl (const QByteArray &encodedUrl, QUrl::ParsingMode parsingMode)
 
void setEncodedUserName (const QByteArray &userName)
 
void setFragment (const QString &fragment, QUrl::ParsingMode mode)
 
void setHost (const QString &host, QUrl::ParsingMode mode)
 
void setPassword (const QString &password, QUrl::ParsingMode mode)
 
void setPath (const QString &path, QUrl::ParsingMode mode)
 
void setPort (int port)
 
void setQuery (const QUrlQuery &query)
 
void setQuery (const QString &query, QUrl::ParsingMode mode)
 
void setQueryItems (const QList< QPair< QString, QString > > &query)
 
void setScheme (const QString &scheme)
 
void setUrl (const QString &url, QUrl::ParsingMode parsingMode)
 
void setUserInfo (const QString &userInfo, QUrl::ParsingMode mode)
 
void setUserName (const QString &userName, QUrl::ParsingMode mode)
 
void swap (QUrl &other)
 
CFURLRef toCFURL () const const
 
QString toDisplayString (QUrl::FormattingOptions options) const const
 
QByteArray toEncoded (QUrl::FormattingOptions options) const const
 
QString toLocalFile () const const
 
NSURL * toNSURL () const const
 
QString topLevelDomain (QUrl::ComponentFormattingOptions options) const const
 
QString toString (QUrl::FormattingOptions options) const const
 
QString url (QUrl::FormattingOptions options) const const
 
QString userInfo (QUrl::ComponentFormattingOptions options) const const
 
QString userName (QUrl::ComponentFormattingOptions options) const const
 

Static Public Member Functions

static KUrl fromPath (const QString &text)
 
static KUrl fromPathOrUrl (const QString &text)
 
static bool isRelativeUrl (const QString &_url)
 
static KUrl join (const List &_list)
 
static QString relativePath (const QString &base_dir, const QString &path, bool *isParent=nullptr)
 
static QString relativeUrl (const KUrl &base_url, const KUrl &url)
 
static List split (const QString &_url)
 
static List split (const KUrl &_url)
 
- Static Public Member Functions inherited from QUrl
QString fromAce (const QByteArray &domain)
 
QUrl fromCFURL (CFURLRef url)
 
QUrl fromEncoded (const QByteArray &input, QUrl::ParsingMode parsingMode)
 
QUrl fromLocalFile (const QString &localFile)
 
QUrl fromNSURL (const NSURL *url)
 
QString fromPercentEncoding (const QByteArray &input)
 
QString fromPunycode (const QByteArray &pc)
 
QList< QUrlfromStringList (const QStringList &urls, QUrl::ParsingMode mode)
 
QUrl fromUserInput (const QString &userInput)
 
QUrl fromUserInput (const QString &userInput, const QString &workingDirectory, QUrl::UserInputResolutionOptions options)
 
QStringList idnWhitelist ()
 
void setIdnWhitelist (const QStringList &list)
 
QByteArray toAce (const QString &domain)
 
QByteArray toPercentEncoding (const QString &input, const QByteArray &exclude, const QByteArray &include)
 
QByteArray toPunycode (const QString &uc)
 
QStringList toStringList (const QList< QUrl > &urls, QUrl::FormattingOptions options)
 

Related Functions

(Note that these are not member functions.)

bool urlcmp (const QString &_url1, const QString &_url2)
 
bool urlcmp (const QString &_url1, const QString &_url2, const KUrl::EqualsOptions &options)
 

Additional Inherited Members

- Public Attributes inherited from QUrl
 AssumeLocalFile
 
typedef ComponentFormattingOptions
 
 DecodedMode
 
 DecodeReserved
 
 DefaultResolution
 
 EncodeDelimiters
 
 EncodeReserved
 
 EncodeSpaces
 
 EncodeUnicode
 
typedef FormattingOptions
 
 FullyDecoded
 
 FullyEncoded
 
 None
 
 NormalizePathSegments
 
 PreferLocalFile
 
 PrettyDecoded
 
 RemoveAuthority
 
 RemoveFilename
 
 RemoveFragment
 
 RemovePassword
 
 RemovePath
 
 RemovePort
 
 RemoveQuery
 
 RemoveScheme
 
 RemoveUserInfo
 
 StrictMode
 
 StripTrailingSlash
 
 TolerantMode
 
typedef UserInputResolutionOptions
 

Detailed Description

Represents and parses a URL.

A prototypical URL looks like:

protocol://user:password\@hostname:port/path/to/file.ext#reference

KUrl handles escaping of URLs. This means that the specification of a full URL will differ from the corresponding string that would specify a local file or directory in file-operations like fopen. This is because an URL doesn't allow certain characters and escapes them. (e.g. '#'->"%23", space->"%20") (In a URL the hash-character '#' is used to specify a "reference", i.e. the position within a document).

The constructor KUrl(const QString&) expects a string properly escaped, or at least non-ambiguous. If you have the absolute path you should use KUrl::fromPath(const QString&).

KUrl kurl = KUrl::fromPath("/bar/#foo#");
QString url = kurl.url(); // -> "file:///bar/%23foo%23"

If you have the URL of a local file or directory and need the absolute path, you would use toLocalFile().

KUrl url( "file:///bar/%23foo%23" );
...
if ( url.isLocalFile() )
QString path = url.toLocalFile(); // -> "/bar/#foo#"

This must also be considered when you have separated directory and file strings and need to put them together. While you can simply concatenate normal path strings, you must take care if the directory-part is already an escaped URL. (This might be needed if the user specifies a relative path, and your program supplies the rest from elsewhere.)

Wrong:

QString dirUrl = "file:///bar/";
QString fileName = "#foo#";
QString invalidURL = dirUrl + fileName; // -> "file:///bar/#foo#" won't behave like you would expect.

Instead you should use addPath(): Right:

KUrl url( "file:///bar/" );
QString fileName = "#foo#";
url.addPath( fileName );
QString validURL = url.url(); // -> "file:///bar/%23foo%23"

Also consider that some URLs contain the password, but this shouldn't be visible. Your program should use prettyUrl() every time it displays a URL, whether in the GUI or in debug output or...

KUrl url( "ftp://name:[email protected]/bar/%23foo%23");
QString visibleURL = url.prettyUrl(); // -> "ftp://[email protected]/bar/%23foo%23"

Note that prettyUrl() doesn't change the character escapes (like "%23"). Otherwise the URL would be invalid and the user wouldn't be able to use it in another context.

Deprecated:
since 5.0; use QUrl directly

Definition at line 109 of file kurl.h.

Member Enumeration Documentation

Options to be used in adjustPath.

Enumerator
RemoveTrailingSlash 

strips a trailing '/', except when the path is already just "/".

LeaveTrailingSlash 

Do not change the path.

AddTrailingSlash 

adds a trailing '/' if there is none yet

Definition at line 118 of file kurl.h.

Options to be used in cleanPath.

Enumerator
SimplifyDirSeparators 

if set, occurrences of consecutive directory separators (e.g.

/foo//bar) are cleaned up as well. (set by default)

KeepDirSeparators 

The opposite of SimplifyDirSeparators.

Definition at line 471 of file kurl.h.

option to be used in fileName and directory

Enumerator
ObeyTrailingSlash 

This tells whether a trailing '/' should be ignored.

If the flag is not set, for both file:///hallo/torben/ and file:///hallo/torben the fileName is "torben" and the path is "hallo"

If the flag is set, then everything behind the last '/'is considered to be the filename. So "hallo/torben" will be the path and the filename will be empty.

AppendTrailingSlash 

tells whether the returned result should end with '/' or not.

If the flag is set, '/' is added to the end of the path

If the path is empty or just "/" then this flag has no effect.

This option should only be used in directory(), it has no effect in fileName()

IgnoreTrailingSlash 

Opposite of ObeyTrailingSlash (default) fileName("file:/foo/") and fileName("file:/foo") is "foo" in both cases.

Definition at line 759 of file kurl.h.

Option to be used in encodedPathAndQuery.

Enumerator
PermitEmptyPath 

Permit empty path (default)

AvoidEmptyPath 

If set to true then an empty path is substituted by "/" (this is the opposite of PermitEmptyPath)

Definition at line 530 of file kurl.h.

Flags to be used in URL comparison functions like equals, or urlcmp.

Enumerator
CompareWithoutTrailingSlash 

ignore trailing '/' characters.

The paths "dir" and "dir/" are treated the same. Note however, that by default, the paths "" and "/" are not the same (For instance ftp://[email protected] redirects to ftp://[email protected]/home/user (on a linux server), while ftp://[email protected]/ is the root dir). This is also why path(RemoveTrailingSlash) for "/" returns "/" and not "".

When dealing with web pages however, you should also set AllowEmptyPath so that no path and "/" are considered equal.

CompareWithoutFragment 

disables comparison of HTML-style references.

AllowEmptyPath 

Treat a URL with no path as equal to a URL with a path of "/", when CompareWithoutTrailingSlash is set.

Example: KUrl::urlcmp("http://www.kde.org", "http://www.kde.org/", KUrl::CompareWithoutTrailingSlash | KUrl::AllowEmptyPath) returns true. This option is ignored if CompareWithoutTrailingSlash isn't set.

Since
4.5

Definition at line 955 of file kurl.h.

Options for queryItems.

Currently, only one option is defined:

Parameters
CaseInsensitiveKeysnormalize query keys to lowercase.

Definition at line 696 of file kurl.h.

Constructor & Destructor Documentation

KUrl::KUrl ( )

Constructs an empty URL.

Definition at line 311 of file kurl.cpp.

KUrl::~KUrl ( )

Destructs the KUrl object.

Definition at line 316 of file kurl.cpp.

KUrl::KUrl ( const QString urlOrPath)

Usual constructor, to construct from a string.

Parameters
urlOrPathAn encoded URL or a path.
Deprecated:
since 5.0, use QUrl(str) if it's a URL, QUrl::fromLocalFile(str) if it's a local path, and QUrl::fromUserInput() if it could be either.

Definition at line 320 of file kurl.cpp.

KUrl::KUrl ( const char *  urlOrPath)
explicit

Constructor taking a char * urlOrPath, which is an encoded representation of the URL, exactly like the usual constructor.

This is useful when the URL, in its encoded form, is strictly ascii.

Parameters
urlOrPathAn encoded URL, or a path.
Deprecated:
since 5.0, use QUrl(str) if it's a URL, QUrl::fromLocalFile(str) if it's a local path, and QUrl::fromUserInput() if it could be either.

Definition at line 355 of file kurl.cpp.

KUrl::KUrl ( const QByteArray urlOrPath)
explicit

Constructor taking a QByteArray urlOrPath, which is an encoded representation of the URL, exactly like the usual constructor.

This is useful when the URL, in its encoded form, is strictly ascii.

Parameters
urlOrPathAn encoded URL, or a path.
Deprecated:
since 5.0, use QUrl(str) if it's a URL, QUrl::fromLocalFile(str) if it's a local path, and QUrl::fromUserInput() if it could be either.

Definition at line 391 of file kurl.cpp.

KUrl::KUrl ( const KUrl u)

Copy constructor.

Parameters
uthe KUrl to copy

Definition at line 415 of file kurl.cpp.

KUrl::KUrl ( const QUrl u)

Converts from a QUrl.

Parameters
uthe QUrl

Definition at line 423 of file kurl.cpp.

KUrl::KUrl ( const KUrl _baseurl,
const QString _rel_url 
)

Constructor allowing relative URLs.

Parameters
_baseurlThe base url.
_rel_urlA relative or absolute URL. If this is an absolute URL then _baseurl will be ignored. If this is a relative URL it will be combined with _baseurl. Note that _rel_url should be encoded too, in any case. So do NOT pass a path here (use setPath or addPath instead).
Deprecated:
since 5.0, use QUrl(_baseurl).resolved(QUrl(_rel_url))

Definition at line 431 of file kurl.cpp.

Member Function Documentation

void KUrl::addPath ( const QString txt)

Adds to the current path.

Assumes that the current path is a directory. txt is appended to the current path. The function adds '/' if needed while concatenating. This means it does not matter whether the current path has a trailing '/' or not. If there is none, it becomes appended. If txt has a leading '/' then this one is stripped.

Parameters
txtThe text to add. It is considered to be decoded.
Deprecated:
since 5.0, use u.setPath(u.path() + '/' + txt). If the path might already have a trailing slash, use u = u.adjusted(QUrl::StripTrailingSlash) first.

Definition at line 1201 of file kurl.cpp.

void KUrl::addQueryItem ( const QString _item,
const QString _value 
)

Add an additional query item.

To replace an existing query item, the item should first be removed with removeQueryItem()

Parameters
_itemName of item to add
_valueValue of item to add
Deprecated:
since 5.0, use QUrlQuery(url), then addQueryItem(), then QUrl::setQuery()

Definition at line 1739 of file kurl.cpp.

void KUrl::adjustPath ( AdjustPathOption  trailing)

Add or remove a trailing slash to/from the path.

If the URL has no path, then no '/' is added anyway. And on the other side: If the path is "/", then this character won't be stripped. Reason: "ftp://weis\@host" means something completely different than "ftp://weis\@host/". So adding or stripping the '/' would really alter the URL, while "ftp://host/path" and "ftp://host/path/" mean the same directory.

Parameters
trailingRemoveTrailingSlash strips any trailing '/' and AddTrailingSlash adds a trailing '/' if there is none yet
Deprecated:
For RemoveTrailingSlash, use url = url.adjusted(QUrl::StripTrailingSlash) (remember to add the assignment!). For AppendTrailingSlash, use: if (!url.path().endsWith('/')) url.setPath(url.path() + '/').

Definition at line 711 of file kurl.cpp.

bool KUrl::cd ( const QString _dir)

Changes the directory by descending into the given directory.

It is assumed the current URL represents a directory. If dir starts with a "/" the current URL will be "protocol://host/dir" otherwise _dir will be appended to the path. _dir can be ".." This function won't strip protocols. That means that when you are in file:///dir/dir2/my.tgz#tar:/ and you do cd("..") you will still be in file:///dir/dir2/my.tgz#tar:/

Parameters
_dirthe directory to change to
Returns
true if successful

Definition at line 1274 of file kurl.cpp.

void KUrl::cleanPath ( const CleanPathOption options = SimplifyDirSeparators)

Resolves "." and ".." components in path.

Some servers seem not to like the removal of extra '/' even though it is against the specification in RFC 2396.

Parameters
optionsuse KeepDirSeparators if you don't want to remove consecutive occurrences of directory separator
Deprecated:
since 5.0, use url.setPath(QDir::cleanPath(url.path())) in file-management code. No replacement available yet for the old HTTP issue mentionned above.

Definition at line 672 of file kurl.cpp.

bool KUrl::cmp ( const KUrl u,
bool  ignore_trailing = false 
) const

The same as equals(), just with a less obvious name.

Compares this url with u.

Parameters
uthe URL to compare this one with.
ignore_trailingset to true to ignore trailing '/' characters.
Returns
True if both urls are the same. If at least one of the urls is invalid, false is returned.
See also
operator==. This function should be used if you want to ignore trailing '/' characters.
Deprecated:
since 4.0, use equals() instead.

Definition at line 538 of file kurl.cpp.

QString KUrl::directory ( const DirectoryOptions options = IgnoreTrailingSlash) const

Returns the directory of the path.

Parameters
optionsa set of DirectoryOption flags
Returns
The directory part of the current path. Everything between the last and the second last '/' is returned. For example file:///hallo/torben/ would return "/hallo/torben/" while file:///hallo/torben would return "hallo/". The returned string is decoded. QString() is returned when there is no path.
Deprecated:
since 5.0, use url.adjusted(QUrl::RemoveFilename).path(), which behaves like ObeyTrailingSlash though. To get rid of the trailing slash if there could be one, use adjusted(QUrl::StripTrailingSlash) first. Do not combine the two calls! You want to remove the trailing slash first, and then remove the filename.

Definition at line 1236 of file kurl.cpp.

QString KUrl::encodedHtmlRef ( ) const

Returns the encoded reference (or "fragment") of the URL (everything after '#').

Returns
the encoded reference, or QString("") if the reference part is empty, or QString() if the URL has no reference.
See also
ref
Deprecated:
since 5.0, use QUrl::fragment(QUrl::FullyEncoded)

Definition at line 1376 of file kurl.cpp.

QString KUrl::encodedPathAndQuery ( AdjustPathOption  trailing = LeaveTrailingSlash,
const EncodedPathAndQueryOptions options = PermitEmptyPath 
) const

Returns the encoded path and the query.

Parameters
trailingadd or remove a trailing '/', see adjustPath
optionsa set of flags from EncodedPathAndQueryOption
Returns
The concatenation of the encoded path , '?' and the encoded query.
Deprecated:
since 5.0, use QUrl::path() and QUrl::query(); QUrl::adjusted() can be used to remove a trailing slash if necessary.

Definition at line 719 of file kurl.cpp.

bool KUrl::equals ( const KUrl u,
const EqualsOptions options = {} 
) const

Compares this url with u.

Parameters
uthe URL to compare this one with.
optionsa set of EqualsOption flags
Returns
True if both urls are the same. If at least one of the urls is invalid, false is returned.
See also
operator==. This function should be used if you want to set additional options, like ignoring trailing '/' characters.
Deprecated:
since 5.0, use matches(u, formattingOptions) equals(u, KUrl::CompareWithoutTrailingSlash) becomes matches(u, QUrl::StripTrailingSlash) equals(u, KUrl::CompareWithoutFragment) becomes matches(u, QUrl::RemoveFragment) equals(u, KUrl::CompareWithoutTrailingSlash|KUrl::AllowEmptyPath) needs manual handling (it was mostly unused).

Definition at line 544 of file kurl.cpp.

QString KUrl::fileEncoding ( ) const

Returns encoding information from url, the content of the "charset" parameter.

Returns
An encoding suitable for QTextCodec::codecForName() or QString() if not encoding was specified.

Definition at line 846 of file kurl.cpp.

QString KUrl::fileName ( const DirectoryOptions options = IgnoreTrailingSlash) const

Returns the filename of the path.

Parameters
optionsa set of DirectoryOption flags. (StripTrailingSlashFromResult has no effect)
Returns
The filename of the current path. The returned string is decoded. Null if there is no file (and thus no path).
Deprecated:
since 5.0, use url.fileName(), which behaves like ObeyTrailingSlash though. To get rid of the trailing slash if there could be one, use adjusted(QUrl::StripTrailingSlash) first.

Definition at line 1150 of file kurl.cpp.

static KUrl KUrl::fromPath ( const QString text)
inlinestatic

Creates a KUrl object from a QString representing an absolute local path.

KUrl url( somePath ) is almost the same, but this method is more explicit, avoids the path-or-url detection in the KUrl constructor, and parses "abc:def" as a filename, not as URL.

Parameters
textthe local path
Returns
the new KUrl
Deprecated:
since 5.0, use QUrl::fromLocalFile

Definition at line 1064 of file kurl.h.

KUrl KUrl::fromPathOrUrl ( const QString text)
static
Deprecated:
since 4.0, use QUrl() instead

Definition at line 1531 of file kurl.cpp.

bool KUrl::hasHost ( ) const
Deprecated:
since 5.0, use QUrl::host() and QString::isEmpty() instead

Definition at line 631 of file kurl.cpp.

bool KUrl::hasHTMLRef ( ) const

Checks whether there is a HTML reference.

Returns
true if the URL has an HTML-style reference.
See also
htmlRef()
Deprecated:
since 5.0, use QUrl::hasFragment()

Definition at line 1400 of file kurl.cpp.

bool KUrl::hasPass ( ) const
Deprecated:
since 5.0, use QUrl::password() and QString::isEmpty() instead

Definition at line 626 of file kurl.cpp.

bool KUrl::hasPath ( ) const
Deprecated:
since 5.0, use QUrl::path() and QString::isEmpty()

Definition at line 636 of file kurl.cpp.

bool KUrl::hasRef ( ) const

Checks whether the URL has a reference/fragment part.

Returns
true if the URL has a reference part. In a URL like http://www.kde.org/kdebase.tar#tar:/README it would return true, too.
Deprecated:
since 5.0, use QUrl::hasFragment()

Definition at line 1759 of file kurl.cpp.

bool KUrl::hasSubUrl ( ) const

Checks whether the URL has any sub URLs.

See split() for examples for sub URLs.

Returns
true if the file has at least one sub URL.
See also
split

Definition at line 931 of file kurl.cpp.

bool KUrl::hasUser ( ) const
Deprecated:
since 5.0, use QUrl::userName() and QString::isEmpty() instead

Definition at line 611 of file kurl.cpp.

QString KUrl::htmlRef ( ) const

Returns the unencoded reference (or "fragment") of the URL (everything after '#').

Returns
the unencoded reference, or QString("") if the reference part is empty, or QString() if the URL has no reference.
See also
split
hasSubUrl
encodedHtmlRef
Deprecated:
since 5.0, use QUrl::fragment(QUrl::FullyDecoded)

Definition at line 1366 of file kurl.cpp.

bool KUrl::isLocalFile ( ) const

Checks whether the file is local.

Returns
true if the file is a plain local file (i.e. uses the file protocol and no hostname, or the local hostname). When isLocalFile returns true, you can use toLocalFile to read the file contents. Otherwise you need to use KIO (e.g. KIO::get).

Definition at line 808 of file kurl.cpp.

bool KUrl::isParentOf ( const KUrl child) const

Checks whether the given URL is parent of this URL.

For instance, ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/.

Returns
true if this url is a parent of u (or the same URL as u)
Deprecated:
since 5.0. url.isParentOf(child) is now url.isParentOf(child) || url.matches(child, QUrl::StripTrailingSlash);

Definition at line 1778 of file kurl.cpp.

bool KUrl::isRelativeUrl ( const QString _url)
static

Convenience function.

Returns whether '_url' is likely to be a "relative" URL instead of an "absolute" URL.

This is mostly meant for KUrl(url, relativeUrl).

If you are looking for the notion of "relative path" (foo) vs "absolute path" (/foo), use QUrl::isRelative() instead. Indeed, isRelativeUrl() returns true for the string "/foo" since it doesn't contain a protocol, while KUrl("/foo").isRelative() is false since the KUrl constructor turns it into file:///foo. The two methods basically test the same thing, but this one takes a string (which is faster) while the class method requires a QUrl/KUrl which gives a more expected result, given the "magic" in the KUrl constructor.

Parameters
_urlURL to examine
Returns
true when the URL is likely to be "relative", false otherwise.
Deprecated:
since 5.0, use QUrl(_url)::isRelative instead

Definition at line 164 of file kurl.cpp.

KUrl KUrl::join ( const List _list)
static

Reverses split().

Only the first URL may have a reference. This reference is considered to be HTML-like and is appended at the end of the resulting joined URL.

Parameters
_listthe list to join
Returns
the joined URL

Definition at line 1127 of file kurl.cpp.

KUrl::operator QVariant ( ) const

Converts this KUrl to a QVariant, this allows to use KUrl in QVariant() constructor.

Definition at line 532 of file kurl.cpp.

QString KUrl::pass ( ) const
Deprecated:
since 5.0, use QUrl::password() instead

Definition at line 616 of file kurl.cpp.

QString KUrl::path ( AdjustPathOption  trailing = LeaveTrailingSlash) const
Parameters
trailinguse to add or remove a trailing slash to/from the path. see adjustPath
Returns
The current decoded path. This does not include the query. Can be QString() if no path is set.
Deprecated:
since 5.0, use OUrl::toLocalFile() for local file urls and QUrl::path() for all other cases. You may use QUrl::isLocalFile() to decide which method to choose. If RemoveTrailingSlash was used, use url.adjusted(QUrl::StripTrailingSlash).path().

Definition at line 758 of file kurl.cpp.

QString KUrl::pathOrUrl ( AdjustPathOption  trailing = LeaveTrailingSlash) const

Return the URL as a string, which will be either the URL (as prettyUrl would return) or, when the URL is a local file without query or ref, the path.

Use this method, to display URLs to the user. You can give the result of pathOrUrl back to the KUrl constructor, it accepts both paths and urls.

Returns
the new KUrl
Parameters
trailinguse to add or remove a trailing slash to/from the path. see adjustPath.
Since
4.2
Deprecated:
since 5.0, use QUrl::toDisplayString(QUrl::PreferLocalFile | ...) instead.

Definition at line 1053 of file kurl.cpp.

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

Adds URL data into the given QMimeData.

By default, populateMimeData also exports the URL as plain text, for e.g. dropping onto a text editor. But in some cases this might not be wanted, e.g. if adding other mime data which provides better plain text data.

WARNING: do not call this method multiple times, use KUrl::List::populateMimeData instead.

Parameters
mimeDatathe QMimeData instance used to drag or copy this URL
metaDataKIO metadata shipped in the mime data, which is used for instance to set a correct HTTP referrer (some websites require it for downloading e.g. an image)
flagsset NoTextExport to prevent setting plain/text data into mimeData
Deprecated:
since 5.0, use QMimeData::setUrls(QList<QUrl>() << url), followed by KUrlMimeData::setMetaData if you have metadata.

Definition at line 1752 of file kurl.cpp.

QString KUrl::prettyUrl ( AdjustPathOption  trailing = LeaveTrailingSlash) const

Returns the URL as string in human-friendly format.

Example:

http://localhost:8080/test.cgi?test=hello world&name=fred
Parameters
trailinguse to add or remove a trailing slash to/from the path. see adjustPath.
Returns
A human readable URL, with no non-necessary encodings/escaped characters. Password will not be shown.
See also
url()
Deprecated:
since 5.0, use QUrl::toDisplayString() instead.

Definition at line 986 of file kurl.cpp.

QString KUrl::protocol ( ) const

Returns the protocol for the URL (i.e., file, http, etc.), lowercased.

Deprecated:
since 5.0, use QUrl::scheme() instead

Definition at line 591 of file kurl.cpp.

QString KUrl::query ( ) const

Returns the query of the URL.

The query may contain the 0 character. If a query is present it always starts with a '?'. A single '?' means an empty query. An empty string means no query.

Returns
The encoded query, or QString() if there is none.
Deprecated:
since 5.0, use QByteArray QUrl::query(), but note that it doesn't start with '?' (QUrl::hasQuery() can be used to distinguish between no query and an empty query).

Definition at line 1439 of file kurl.cpp.

QString KUrl::queryItem ( const QString item) const

Returns the value of a certain query item.

This does the same as QUrl::queryItemValue(), except that it decodes "+" into " " in the value.

Parameters
itemItem whose value we want
Returns
the value of the given query item name or QString() if the specified item does not exist.
Deprecated:
since 5.0, use QUrlQuery(url).queryItemValue(item)

Definition at line 1714 of file kurl.cpp.

QMap< QString, QString > KUrl::queryItems ( const QueryItemsOptions options = {}) const

Returns the list of query items as a map mapping keys to values.

This does the same as QUrl::queryItems(), except that it decodes "+" into " " in the value, supports CaseInsensitiveKeys, and returns a different data type.

Parameters
optionsany of QueryItemsOption ored together.
Returns
the map of query items or the empty map if the url has no query items.
Deprecated:
since 5.0, use QUrlQuery(url).queryItems()

Definition at line 1678 of file kurl.cpp.

QString KUrl::ref ( ) const

Returns the encoded reference (or "fragment") of the URL (everything after '#').

Returns
the encoded reference, or QString("") if the reference part is empty, or QString() if the URL has no reference.
Deprecated:
since 5.0, use QUrl::fragment(QUrl::FullyEncoded)

Definition at line 1769 of file kurl.cpp.

QString KUrl::relativePath ( const QString base_dir,
const QString path,
bool *  isParent = nullptr 
)
static

Convenience function.

Returns a relative path based on base_dir that points to path.

Parameters
base_dirthe base directory to derive from
paththe new target directory
isParentA pointer to a boolean which, if provided, will be set to reflect whether path has base_dir is a parent dir.
Deprecated:
since 5.0, use QDir(base_dir).relativeFilePath(path). isParent can be replaced with a call to startsWith("..") on the result value.

Definition at line 1589 of file kurl.cpp.

QString KUrl::relativeUrl ( const KUrl base_url,
const KUrl url 
)
static

Convenience function.

Returns a "relative URL" based on base_url that points to url.

If no "relative URL" can be created, e.g. because the protocol and/or hostname differ between base_url and url an absolute URL is returned. Note that if base_url represents a directory, it should contain a trailing slash.

Parameters
base_urlthe URL to derive from
urlnew URL
See also
adjustPath()
Deprecated:
since 5.0, check that the URLs have the same scheme+host+port+user+pass, then make the path relative with QDir(base_url.path()).relativeFilePath(url.path())

Definition at line 1604 of file kurl.cpp.

void KUrl::setDirectory ( const QString dir)

Set the directory to dir, leaving the filename empty.

Definition at line 1410 of file kurl.cpp.

void KUrl::setEncodedPathAndQuery ( const QString _txt)

This is useful for HTTP.

It looks first for '?' and decodes then. The encoded path is the concatenation of the current path and the query.

Parameters
_txtthe new path and query.
Deprecated:
since 5.0, use QUrl::setPath() and QUrl::fromPercentEncoding() to set the encoded path; use QUrl::setQuery() with an appropriate QUrl::ParsingMode value to set the query.

Definition at line 746 of file kurl.cpp.

void KUrl::setFileEncoding ( const QString encoding)

Adds encoding information to url by adding a "charset" parameter.

If there is already a charset parameter, it will be replaced.

Parameters
encodingthe encoding to add or QString() to remove the encoding.

Definition at line 813 of file kurl.cpp.

void KUrl::setFileName ( const QString _txt)

Sets the filename of the path.

In comparison to addPath() this function does not assume that the current path is a directory. This is only assumed if the current path ends with '/'.

Any reference is reset.

Parameters
_txtThe filename to be set. It is considered to be decoded. If the current path ends with '/' then _txt int just appended, otherwise all text behind the last '/' in the current path is erased and _txt is appended then. It does not matter whether _txt starts with '/' or not.
Deprecated:
since 5.0, use u = u.adjusted(QUrl::RemoveFilename); followed by u.setPath(u.path() + txt);

Definition at line 641 of file kurl.cpp.

void KUrl::setHTMLRef ( const QString ref)

Sets the HTML-style reference.

Parameters
refThe new reference. This is considered to be not encoded in contrast to setRef(). Use QString() to remove it.
See also
htmlRef()
Deprecated:
since 5.0, use QUrl::setFragment(ref, QUrl::DecodedMode)

Definition at line 1386 of file kurl.cpp.

void KUrl::setPass ( const QString pass)
Deprecated:
since 5.0, use QUrl::setPassword() instead

Definition at line 621 of file kurl.cpp.

void KUrl::setPath ( const QString path)

KUrl's setPath on an empty url implies the "file" protocol.

Deprecated:
since 5.0, use QUrl::fromLocalFile instead, for the case of local paths. Do not port to QUrl u; u.setPath(...); since that would lead to a URL without a scheme!

Definition at line 1636 of file kurl.cpp.

void KUrl::setProtocol ( const QString proto)
Deprecated:
since 5.0, use QUrl::setScheme() instead

Definition at line 596 of file kurl.cpp.

void KUrl::setQuery ( const QString query)
Parameters
queryThis is considered to be encoded. This has a good reason: The query may contain the 0 character.

The query should start with a '?'. If it doesn't '?' is prepended.

Deprecated:
since 5.0, use QUrl::setQuery(QString), but note that it doesn't start with '?' (it uses null vs empty, instead).

Definition at line 1419 of file kurl.cpp.

void KUrl::setRef ( const QString fragment)

Sets the reference/fragment part (everything after '#').

If you have an encoded fragment already (as a QByteArray), you can call setFragment directly.

Parameters
fragmentthe encoded reference (or QString() to remove it).
Deprecated:
since 5.0, use QUrl::setFragment()

Definition at line 1764 of file kurl.cpp.

void KUrl::setUser ( const QString user)
Deprecated:
since 5.0, use QUrl::setUserName() instead

Definition at line 606 of file kurl.cpp.

KUrl::List KUrl::split ( const QString _url)
static

Splits nested URLs like file:///home/weis/kde.tgz#gzip:/#tar:/kdebase A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in http://www.kde.org and tar:/kde/README.html::ref1.

That means in turn that "#ref1" is an HTML-style reference and not a new sub URL. Since HTML-style references mark a certain position in a document this reference is appended to every URL. The idea behind this is that browsers, for example, only look at the first URL while the rest is not of interest to them.

Parameters
_urlThe URL that has to be split.
Returns
An empty list on error or the list of split URLs.
See also
hasSubUrl

Definition at line 1122 of file kurl.cpp.

KUrl::List KUrl::split ( const KUrl _url)
static

Splits nested URLs like file:///home/weis/kde.tgz#gzip:/#tar:/kdebase A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in http://www.kde.org and tar:/kde/README.html::ref1.

That means in turn that "#ref1" is an HTML-style reference and not a new sub URL. Since HTML-style references mark a certain position in a document this reference is appended to every URL. The idea behind this is that browsers, for example, only look at the first URL while the rest is not of interest to them.

Returns
An empty list on error or the list of split URLs.
Parameters
_urlThe URL that has to be split.
See also
hasSubUrl

Definition at line 1091 of file kurl.cpp.

QString KUrl::toLocalFile ( AdjustPathOption  trailing = LeaveTrailingSlash) const
Parameters
trailinguse to add or remove a trailing slash to/from the local path. see adjustPath
Returns
The current local path. Can be QString() if no path is set.
Deprecated:
since 5.0, use QUrl::toLocalFile() instead; if RemoveTrailingSlash was used, use url.adjusted(QUrl::StripTrailingSlash).toLocalFile()

Definition at line 772 of file kurl.cpp.

QString KUrl::toMimeDataString ( ) const

Returns the URL as a string, using the standard conventions for mime data (drag-n-drop or copy-n-paste).

Internally used by KUrl::List::fromMimeData, which is probably what you want to use instead.

Deprecated:
since 5.0, use QMimeData::setUrls directly, or KUrlMimeData::setUrls

Definition at line 1063 of file kurl.cpp.

KUrl KUrl::upUrl ( ) const

This function is useful to implement the "Up" button in a file manager for example.

cd() never strips a sub-protocol. That means that if you are in file:///home/x.tgz#gzip:/#tar:/ and hit the up button you expect to see file:///home. The algorithm tries to go up on the right-most URL. If that is not possible it strips the right most URL. It continues stripping URLs.

Returns
a URL that is a level higher
Deprecated:
since 5.0, use KIO::upUrl() instead, from kio/global.h

Definition at line 1328 of file kurl.cpp.

QString KUrl::url ( AdjustPathOption  trailing = LeaveTrailingSlash) const

Returns the URL as string, with all escape sequences intact, encoded in a given charset.

This is used in particular for encoding URLs in UTF-8 before using them in a drag and drop operation. Please note that the string returned by url() will include the password of the URL. If you want to show the URL to the user, use prettyUrl().

Parameters
trailinguse to add or remove a trailing slash to/from the path. See adjustPath
Returns
The complete URL, with all escape sequences intact, encoded in a given charset.
See also
prettyUrl()
Deprecated:
since 5.0, use QUrl::toString() instead. In case of RemoveTrailingSlash, call adjusted(QUrl::StripTrailingSlash) first. AddTrailingSlash is not available directly, test if path ends with '/', and if not setPath(path() + '/').

Definition at line 936 of file kurl.cpp.

QString KUrl::user ( ) const
Deprecated:
since 5.0, use QUrl::userName() instead

Definition at line 601 of file kurl.cpp.

Friends And Related Function Documentation

bool urlcmp ( const QString _url1,
const QString _url2 
)
related

Compares URLs. They are parsed, split and compared. Two malformed URLs with the same string representation are nevertheless considered to be unequal. That means no malformed URL equals anything else.

Deprecated:
since 4.5, use QUrl(_url1) == QUrl(_url2) instead.

Definition at line 1456 of file kurl.cpp.

bool urlcmp ( const QString _url1,
const QString _url2,
const KUrl::EqualsOptions options 
)
related

Compares URLs. They are parsed, split and compared. Two malformed URLs with the same string representation are nevertheless considered to be unequal. That means no malformed URL equals anything else.

Parameters
_url1A reference URL
_url2A URL that will be compared with the reference URL
optionsa set of KUrl::EqualsOption flags
Deprecated:
since 4.5, use QUrl(_url1).adjusted(options) == QUrl(_url2).adjusted(options) instead.

Definition at line 1483 of file kurl.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Dec 3 2020 22:59:39 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.