#include <KUrl>

Inheritance diagram for KUrl:

Classes
class	List

Public Types
enum	AdjustPathOption { RemoveTrailingSlash, LeaveTrailingSlash, AddTrailingSlash }

enum	CleanPathOption { SimplifyDirSeparators = 0x00, KeepDirSeparators = 0x01 }

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

enum	EncodedPathAndQueryOption { PermitEmptyPath =0x00, AvoidEmptyPath =0x01 }

enum	EqualsOption { CompareWithoutTrailingSlash = 0x01, CompareWithoutFragment = 0x02, AllowEmptyPath = 0x04 }

typedef QMap< QString, QString >	MetaDataMap

enum	MimeDataFlags { DefaultMimeDataFlags = 0, NoTextExport = 1 }

enum	QueryItemsOption { CaseInsensitiveKeys = 1 }

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=0) 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 &u) const

	operator QVariant () const

bool	operator!= (const KUrl &_u) const

bool	operator!= (const QString &_u) const

KUrl &	operator= (const KUrl &_u)

KUrl &	operator= (const char *_url)

KUrl &	operator= (const QByteArray &_url)

KUrl &	operator= (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 () const

QString	pathOrUrl (AdjustPathOption trailing) 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, QString >	queryItems (const QueryItemsOptions &options=0) 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

Static Public Member Functions
static QString	decode_string (const QString &str)

static QString	encode_string (const QString &str)

static QString	encode_string_no_slash (const QString &str)

static KUrl	fromMimeDataByteArray (const QByteArray &str)

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=0)

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

static List	split (const QString &_url)

static List	split (const KUrl &_url)

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)

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:password@ftp.faraway.org/bar/%23foo%23");

QString visibleURL = url.prettyUrl(); // -> "ftp://name@ftp.faraway.org/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.

Definition at line 111 of file kurl.h.

Member Typedef Documentation

typedef QMap<QString, QString> KUrl::MetaDataMap

Definition at line 114 of file kurl.h.

Member Enumeration Documentation

enum KUrl::AdjustPathOption

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 120 of file kurl.h.

enum KUrl::CleanPathOption

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 463 of file kurl.h.

enum KUrl::DirectoryOption

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 734 of file kurl.h.

enum KUrl::EncodedPathAndQueryOption

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 524 of file kurl.h.

enum KUrl::EqualsOption

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://user@host redirects to ftp://user@host/home/user (on a linux server), while ftp://user@host/ 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 905 of file kurl.h.

enum KUrl::MimeDataFlags

Enumerator
DefaultMimeDataFlags
NoTextExport

Definition at line 115 of file kurl.h.

enum KUrl::QueryItemsOption

Options for queryItems.

Currently, only one option is defined:

Parameters

CaseInsensitiveKeys normalize query keys to lowercase.

Enumerator
CaseInsensitiveKeys

Definition at line 673 of file kurl.h.

Constructor & Destructor Documentation

KUrl::KUrl ( )

Constructs an empty URL.

Definition at line 390 of file kurl.cpp.

KUrl::~KUrl ( )

Destructs the KUrl object.

Definition at line 395 of file kurl.cpp.

KUrl::KUrl ( const QString & urlOrPath )

Usual constructor, to construct from a string.

Parameters

urlOrPath An encoded URL or a path.

Definition at line 400 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

urlOrPath An encoded URL, or a path.

Definition at line 434 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

urlOrPath An encoded URL, or a path.

Definition at line 468 of file kurl.cpp.

KUrl::KUrl ( const KUrl & u )

Copy constructor.

Parameters

u	the KUrl to copy

Definition at line 489 of file kurl.cpp.

KUrl::KUrl ( const QUrl & u )

Converts from a QUrl.

Parameters

u the QUrl

Definition at line 497 of file kurl.cpp.

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

Constructor allowing relative URLs.

Parameters

_baseurl	The base url.
_rel_url	A 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).

Definition at line 505 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

txt	The text to add. It is considered to be decoded.

Definition at line 1343 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

_item	Name of item to add
_value	Value of item to add

Definition at line 1867 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

trailing RemoveTrailingSlash strips any trailing '/' and AddTrailingSlash adds a trailing '/' if there is none yet

Definition at line 802 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

_dir	the directory to change to

Returns: true if successful

Definition at line 1419 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

options use KeepDirSeparators if you don't want to remove consecutive occurrences of directory separator

Definition at line 759 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

u	the URL to compare this one with.
ignore_trailing	set 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:: Use equals() instead.

Definition at line 625 of file kurl.cpp.

static QString KUrl::decode_string ( const QString & str )

inlinestatic

Decode %-style encoding and convert from local encoding to unicode.

Reverse of encode_string()

Parameters

str	String to decode (can be QString()).

Deprecated:: use QUrl::fromPercentEncoding(encodedURL) instead, but note that it takes a QByteArray and not a QString. Which makes sense since everything is 7 bit (ascii) when being percent-encoded.

Definition at line 1090 of file kurl.h.

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

Returns the directory of the path.

Parameters

options a 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.

Definition at line 1379 of file kurl.cpp.

static QString KUrl::encode_string ( const QString & str )

inlinestatic

Convert unicoded string to local encoding and use %-style encoding for all common delimiters / non-ascii characters.

Parameters

str	String to encode (can be QString()).

Returns: the encoded string

Deprecated:: use QUrl::toPercentEncoding instead, but note that it returns a QByteArray and not a QString. Which makes sense since everything is 7 bit (ascii) after being percent-encoded.

Definition at line 1057 of file kurl.h.

static QString KUrl::encode_string_no_slash ( const QString & str )

inlinestatic

Convert unicoded string to local encoding and use %-style encoding for all common delimiters / non-ascii characters as well as the slash '/'.

Parameters

str	String to encode

Deprecated:: use QUrl::toPercentEncoding(str,"/") instead, but note that it returns a QByteArray and not a QString. Which makes sense since everything is 7 bit (ascii) after being percent-encoded.

Definition at line 1074 of file kurl.h.

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

Definition at line 1524 of file kurl.cpp.

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

Returns the encoded path and the query.

Parameters

trailing	add or remove a trailing '/', see adjustPath
options	a set of flags from EncodedPathAndQueryOption

Returns: The concatenation of the encoded path , '?' and the encoded query.

Definition at line 816 of file kurl.cpp.

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

Compares this url with u.

Parameters

u	the URL to compare this one with.
options	a 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.

Definition at line 631 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 958 of file kurl.cpp.

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

Returns the filename of the path.

Parameters

options a 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).

Definition at line 1282 of file kurl.cpp.

KUrl KUrl::fromMimeDataByteArray ( const QByteArray & str )

static

Creates a KUrl from 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.

Definition at line 1210 of file kurl.cpp.

KUrl KUrl::fromPath ( const QString & text )

static

Creates a KUrl object from a QString representing an absolute 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

text the path

Returns: the new KUrl

Definition at line 722 of file kurl.cpp.

KUrl KUrl::fromPathOrUrl ( const QString & text )

static

Deprecated:: Since KDE4 you can pass both urls and paths to the KUrl constructors. Use KUrl(text) instead.

Definition at line 1672 of file kurl.cpp.

bool KUrl::hasHost ( ) const

Test to see if this URL has a hostname included in it.

Returns: true if the URL has a host

Definition at line 712 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()

Definition at line 1550 of file kurl.cpp.

bool KUrl::hasPass ( ) const

Test to see if this URL has a password included in it.

Returns: true if there is a non-empty password set

Definition at line 707 of file kurl.cpp.

bool KUrl::hasPath ( ) const

Test to see if this URL has a path is included in it.

Returns: true if there is a path

Definition at line 717 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.

Definition at line 1887 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 1030 of file kurl.cpp.

bool KUrl::hasUser ( ) const

Test to see if this URL has a user name included in it.

Returns: true if the URL has an non-empty user name

Definition at line 692 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

Definition at line 1513 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 924 of file kurl.cpp.

bool KUrl::isParentOf ( const KUrl & u ) 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)

Definition at line 1908 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

_url	URL to examine

Returns: true when the URL is likely to be "relative", false otherwise.

Definition at line 160 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

_list the list to join

Returns: the joined URL

Definition at line 1260 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 619 of file kurl.cpp.

bool KUrl::operator!= ( const KUrl & _u ) const

inline

Definition at line 877 of file kurl.h.

bool KUrl::operator!= ( const QString & _u ) const

inline

Definition at line 878 of file kurl.h.

KUrl & KUrl::operator= ( const KUrl & _u )

Definition at line 602 of file kurl.cpp.

KUrl& KUrl::operator= ( const char * _url )

inline

Definition at line 871 of file kurl.h.

KUrl& KUrl::operator= ( const QByteArray & _url )

inline

Definition at line 872 of file kurl.h.

KUrl& KUrl::operator= ( const QString & _url )

inline

Definition at line 873 of file kurl.h.

bool KUrl::operator== ( const KUrl & _u ) const

Definition at line 608 of file kurl.cpp.

bool KUrl::operator== ( const QString & _u ) const

Definition at line 613 of file kurl.cpp.

QString KUrl::pass ( ) const

Returns the decoded password (corresponding to user()) included in the URL.

Returns: the password or QString() if it does not exist

Definition at line 697 of file kurl.cpp.

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

Parameters

trailing use 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.

Definition at line 873 of file kurl.cpp.

QString KUrl::pathOrUrl ( ) 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

Definition at line 1164 of file kurl.cpp.

QString KUrl::pathOrUrl ( AdjustPathOption trailing ) const

Overload with trailing parameter.

Parameters

trailing use to add or remove a trailing slash to/from the path. see adjustPath.

Since: 4.2

Definition at line 1169 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

mimeData	the QMimeData instance used to drag or copy this URL
metaData	KIO 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)
flags	set NoTextExport to prevent setting plain/text data into `mimeData` In such a case, setExportAsText( false ) should be called.

Definition at line 1879 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

trailing use 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()

Definition at line 1086 of file kurl.cpp.

QString KUrl::protocol ( ) const

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

See also: QUrl::scheme

Definition at line 672 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.

Definition at line 1588 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

item	Item whose value we want

Returns: the value of the given query item name or QString() if the specified item does not exist.

Definition at line 1840 of file kurl.cpp.

QMap< QString, QString > KUrl::queryItems ( const QueryItemsOptions & options = 0 ) 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

options any of QueryItemsOption ored together.

Returns: the map of query items or the empty map if the url has no query items.

Definition at line 1807 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.

Definition at line 1900 of file kurl.cpp.

QString KUrl::relativePath	(	const QString &	base_dir,
		const QString &	path,
		bool *	isParent = `0`
	)

static

Convenience function.

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

Parameters

base_dir	the base directory to derive from
path	the new target directory
isParent	A pointer to a boolean which, if provided, will be set to reflect whether `path` has `base_dir` is a parent dir.

Definition at line 1723 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_url	the URL to derive from
url	new URL

See also: adjustPath()

Definition at line 1737 of file kurl.cpp.

void KUrl::setDirectory ( const QString & dir )

Set the directory to dir, leaving the filename empty.

Definition at line 1561 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

_txt	the new path and query.

Definition at line 858 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

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

Definition at line 929 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

_txt	The 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.

Definition at line 729 of file kurl.cpp.

void KUrl::setHTMLRef ( const QString & _ref )

Sets the HTML-style reference.

Parameters

_ref	The new reference. This is considered to be not encoded in contrast to setRef(). Use QString() to remove it.

See also: htmlRef()

Definition at line 1535 of file kurl.cpp.

void KUrl::setPass ( const QString & pass )

Sets the password (corresponding to user()) included in the URL.

Special characters in the password will appear encoded in the URL. Note that a password can only appear in a URL string if you also set a user.

Parameters

pass	the password to set or QString() to remove the password

See also: setUser; hasUser

Definition at line 702 of file kurl.cpp.

void KUrl::setPath ( const QString & path )

Reimplemented from superclass. so that KUrl u; u.setPath(path); implies "file" protocol.

Definition at line 1771 of file kurl.cpp.

void KUrl::setProtocol ( const QString & proto )

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

Parameters

proto the new protocol of the URL (without colon)

Definition at line 677 of file kurl.cpp.

void KUrl::setQuery ( const QString & query )

Parameters

query This 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.

Definition at line 1569 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 setEncodedFragment directly.

Parameters

fragment the encoded reference (or QString() to remove it).

Definition at line 1892 of file kurl.cpp.

void KUrl::setUser ( const QString & user )

Sets the user name (login, user id, ...) included in the URL.

Special characters in the user name will appear encoded in the URL.

Parameters

user	the name of the user or QString() to remove the user

Definition at line 687 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

_url	The URL that has to be split.

Returns: An empty list on error or the list of split URLs.

See also: hasSubUrl

Definition at line 1255 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

_url	The URL that has to be split.

See also: hasSubUrl

Definition at line 1218 of file kurl.cpp.

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

Parameters

trailing use 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.

Definition at line 885 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.

Definition at line 1179 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

Definition at line 1476 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

trailing use 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()

Definition at line 1035 of file kurl.cpp.

QString KUrl::user ( ) const

Returns the decoded user name (login, user id, ...) included in the URL.

Returns: the user name or QString() if there is no user name

Definition at line 682 of file kurl.cpp.

Friends And Related Function Documentation

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

Deprecated:: use KUrl(_url1).equals(KUrl(_url2)) instead.

Definition at line 1604 of file kurl.cpp.

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

Parameters

_url1	A reference URL
_url2	A URL that will be compared with the reference URL
options	a set of KUrl::EqualsOption flags

Deprecated:: use KUrl(_url1).equals(KUrl(_url2), options) instead.

Definition at line 1628 of file kurl.cpp.

The documentation for this class was generated from the following files:

KDECore

Classes

Public Types

Public Member Functions

Static Public Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

KDECore

kdelibs API Reference

Search