KDE 4.5 PyKDE API Reference

- KDE's Python API

# KUriFilterData Class Reference

`from PyKDE4.kio import *`

## Detailed Description

A basic message object used for exchanging filtering information between the filter plugins and the application requesting the filtering service.

Use this object if you require a more detailed information about the URI you want to filter. Any application can create an instance of this class and send it to KUriFilter to have the plugins fill out all possible information about the URI.

The member functions provided by this class are thread safe and reentrant. However, since the class itself is a Singleton, you have to take care when calling self() in multi-threaded applications. It is highly adviced that you hold a member variable

Example

       QString text = "kde.org";
       KUriFilterData d = text;
       bool filtered = KUriFilter.self()->filter( d );
       cout << "URL: " << text.toLatin1() << endl
            << "Filtered URL: " << d.uri().url().toLatin1() << endl
            << "URI Type: " << d.uriType() << endl
            << "Was Filtered: " << filtered << endl;

The above code should yield the following output:

       URI: kde.org
       Filtered URI: http://kde.org
       URI Type: 0            <== means NET_PROTOCOL
       Was Filtered: 1        <== means the URL was successfully filtered

A message object for exchanging filtering URI info.

Author:
  Dawit Alemayehu <adawit at kde.org>

## Enumerations

UriTypes | { NetProtocol, LocalFile, LocalDir, Executable, Help, Shell, Blocked, Error, Unknown }

## Methods

| __init__ (self)
| __init__ (self, KUrl url)
| __init__ (self, QString url)
| __init__ (self, KUriFilterData other)
QString | absolutePath (self)
QString | alternateDefaultSearchProvider (self)
QStringList | alternateSearchProviders (self)
QString | argsAndOptions (self)
bool | checkForExecutables (self)
QString | errorMsg (self)
bool | hasAbsolutePath (self)
bool | hasArgsAndOptions (self)
QString | iconName (self)
QString | iconNameForPreferredSearchProvider (self, QString provider)
QStringList | preferredSearchProviders (self)
QString | queryForPreferredSearchProvider (self, QString provider)
QString | searchProvider (self)
QString | searchTerm (self)
QChar | searchTermSeparator (self)
bool | setAbsolutePath (self, QString abs_path)
| setAlternateDefaultSearchProvider (self, QString provider)
| setAlternateSearchProviders (self, QStringList providers)
| setCheckForExecutables (self, bool check)
| setData (self, KUrl url)
| setData (self, QString url)
QString | typedString (self)
KUrl | uri (self)
KUriFilterData.UriTypes | uriType (self)

## Method Documentation

__init__ | ( |  | self ) |

Default constructor.

Creates a UriFilterData object.

__init__ | ( | self, |
|  | KUrl | url
| ) |  |  |

Creates a KUriFilterData object from the given string.

Parameters:

  | url | is the string to be filtered.

__init__ | ( | self, |
|  | QString | url
| ) |  |  |

Creates a KUriFilterData object from the given string.

Parameters:

  | url | is the string to be filtered.

__init__ | ( | self, |
|  | KUriFilterData | other
| ) |  |  |

Copy constructor.

Creates a KUriFilterData object from another KURIFilterData object.

Parameters:

  | other | the uri filter data to be copied.

QString absolutePath | ( |  | self ) |

Returns the absolute path if one has already been set.

Returns:
  the absolute path, or QString()

See also:
  hasAbsolutePath()

QString alternateDefaultSearchProvider | ( |  | self ) |

Returns the search provider to use when a default provider is not available.

The alternate default search provider is not set by default and this function returns an empty string.

See also:
  setAlternateDefaultSearchProvider

Since:
  4.5

QStringList alternateSearchProviders | ( |  | self ) |

Returns the list of alternate search providers.

This function returns an empty list if setAlternateSearchProviders was not called to set alternate search providers to be used in place of the preferred search providers when they are not available.

See also:
  setAlternatteSearchProviders

See also:
  preferredSearchProviders

Since:
  4.5

QString argsAndOptions | ( |  | self ) |

Returns the command line options and arguments for a local resource when present.

Returns:
  options and arguments when present, otherwise QString()

bool checkForExecutables | ( |  | self ) |

Returns:
  true if the filters should attempt to check whether the supplied uri is an executable. False otherwise.

QString errorMsg | ( |  | self ) |

Returns an error message.

This functions returns the error message set by the plugin whenever the uri type is set to KUriFilterData.ERROR. Otherwise, it returns a NULL string.

Returns:
  the error message or a NULL when there is none.

bool hasAbsolutePath | ( |  | self ) |

Checks whether the supplied data had an absolute path.

Returns:
  true if the supplied data has an absolute path

See also:
  absolutePath()

bool hasArgsAndOptions | ( |  | self ) |

Checks whether the current data is a local resource with command line options and arguments.

Returns:
  true if the current data has command line options and arguments

QString iconName | ( |  | self ) |

The name of the icon that matches the current filtered URL.

This function returns a null string by default and when no icon is found for the filtered URL.

QString iconNameForPreferredSearchProvider | ( | self, |
|  | QString | provider
| ) |  |  |

Returns the icon associated with the given preferred search provider.

You can use this function to obtain the icon names associated with the preferred search providers returned by preferredSearchProviders.

See also:
  preferredSearchProviders

Since:
  4.5

QStringList preferredSearchProviders | ( |  | self ) |

Returns a list of the names of the preferred search providers.

This function returns the list of favorite or preferred providers only when this data filtered through the default search uri plugin 'kurisearchfilter'. Otherwise, it returns an empty list.

You can use queryForPreferredServiceProvider to obtain the queries associated with the returned search providers.

See also:
  searchProvider

Since:
  4.5

QString queryForPreferredSearchProvider | ( | self, |
|  | QString | provider
| ) |  |  |

Returns the query url for the given preferred search provider.

You can use this function to obtain the query for the preferred search providers returned by preferredSearchProviders. Note that this function actually returns a query, e.g. "gg:foo bar", that must be processed using the KUriFilter class.

See also:
  preferredSearchProviders

Since:
  4.5

QString searchProvider | ( |  | self ) |

Returns the name of the search service provider, e.g. Google.

If typedString was not filtered by a search filter plugin, this function returns an empty string.

See also:
  typedString

Since:
  4.5

QString searchTerm | ( |  | self ) |

Returns the search term portion of the typed string.

If the typedString was not filtered by a search filter plugin, this function returns an empty string.

See also:
  typedString

Since:
  4.5

QChar searchTermSeparator | ( |  | self ) |

Returns the character that is used to separate the search term from the keyword.

If typedString was not filtered by a search filter plugin, this function returns a null charater.

See also:
  typedString

Since:
  4.5

bool setAbsolutePath | ( | self, |
|  | QString | abs_path
| ) |  |  |

Sets the absolute path to be used whenever the supplied data is a relative local URL.

NOTE: This function should only be used for local resources, i.e. the "file:/" protocol. It is useful for specifying the absolute path in cases where the actual URL might be relative. If deriving the path from a KUrl, make sure you set the argument for this function to the result of calling path () instead of url ().

Parameters:

  | abs_path | the abolute path to the local resource.

Returns:
  true if absolute path is successfully set. Otherwise, false.

setAlternateDefaultSearchProvider | ( | self, |
|  | QString | provider
| ) |  |  |

Sets the search provider to use when there no default provider has been set by though the web shortcuts configuration dialog.

See also:
  setAlternateDefaultSearchProvider

Since:
  4.5

setAlternateSearchProviders | ( | self, |
|  | QStringList | providers
| ) |  |  |

Sets a list of search providers to use in case no default preferred search providers are available.

The list of preferred search providers set using this function will only be used if the default and favorite search providers have not yet been configured through the configuration dialogs. Otherwise, the providers specified by this function will be ignored.

See also:
  alternatteSearchProviders

See also:
  preferredSearchProviders

Since:
  4.5

setCheckForExecutables | ( | self, |
|  | bool | check
| ) |  |  |

Check whether the provided uri is executable or not.

Setting this to false ensures that typing the name of an executable does not start that application. This is useful in the location bar of a browser. The default value is true.

setData | ( | self, |
|  | KUrl | url
| ) |  |  |

Sets the URL to be filtered.

Use this function to set the string to be filtered when you construct an empty filter object.

Parameters:

  | url | the string to be filtered.

setData | ( | self, |
|  | QString | url
| ) |  |  |

Sets the URL to be filtered.

Use this function to set the string to be filtered when you construct an empty filter object.

Parameters:

  | url | the string to be filtered.

QString typedString | ( |  | self ) |

The string as typed by the user, before any URL processing is done.

KUrl uri | ( |  | self ) |

Returns the filtered or the original URL.

If one of the plugins successfully filtered the original input, this function returns it. Otherwise, it will return the input itself.

Returns:
  the filtered or original url.

KUriFilterData.UriTypes uriType | ( |  | self ) |

Returns the URI type.

This method always returns KUriFilterData.UNKNOWN if the given URL was not filtered.

Returns:
  the type of the URI

## Enumeration Documentation

UriTypes

Describes the type of the URI that was filtered. Here is a brief description of the types:

- NetProtocol - Any network protocol: http, ftp, nttp, pop3, etc...
- LocalFile - A local file whose executable flag is not set
- LocalDir - A local directory
- Executable - A local file whose executable flag is set
- Help - A man or info page
- Shell - A shell executable (ex: echo "Test..." >> ~/testfile)
- Blocked - A URI that should be blocked/filtered (ex: ad filtering)
- Error - An incorrect URI (ex: "~johndoe" when user johndoe
does not exist in that system )
- Unknown - A URI that is not identified. Default value when
a KUriFilterData is first created.

Enumerator:

  NetProtocol = 0 |
  LocalFile |
  LocalDir |
  Executable |
  Help |
  Shell |
  Blocked |
  Error |
  Unknown |