KDirLister Class Reference

`#include <kdirlister.h>`

Inherits QObject.

## Public Types

enum | WhichItems { AllItems = 0, FilteredItems = 1 }

## Signals

void | started (const KURL &_url)
void | completed ()
void | completed (const KURL &_url)
void | canceled ()
void | canceled (const KURL &_url)
void | redirection (const KURL &_url)
void | redirection (const KURL &oldUrl, const KURL &newUrl)
void | clear ()
void | clear (const KURL &_url)
void | newItems (const KFileItemList &items)
void | itemsFilteredByMime (const KFileItemList &items)
void | deleteItem (KFileItem *_fileItem)
void | refreshItems (const KFileItemList &items)
void | infoMessage (const QString &msg)
void | percent (int percent)
void | totalSize (KIO::filesize_t size)
void | processedSize (KIO::filesize_t size)
void | speed (int bytes_per_second)

## Public Member Functions

| KDirLister (bool _delayedMimeTypes=false)
virtual | ~KDirLister ()
virtual bool | openURL (const KURL &_url, bool _keep=false, bool _reload=false)
virtual void | stop ()
virtual void | stop (const KURL &_url)
bool | autoUpdate () const
virtual void | setAutoUpdate (bool enable)
bool | autoErrorHandlingEnabled () const
void | setAutoErrorHandlingEnabled (bool enable, QWidget *parent)
bool | showingDotFiles () const
virtual void | setShowingDotFiles (bool _showDotFiles)
bool | dirOnlyMode () const
virtual void | setDirOnlyMode (bool dirsOnly)
const KURL & | url () const
const KURL::List & | directories () const
virtual void | emitChanges ()
virtual void | updateDirectory (const KURL &_dir)
bool | isFinished () const
KFileItem * | rootItem () const
virtual KFileItem * | findByURL (const KURL &_url) const
KFileItem * | find (const KURL &_url) const
virtual KFileItem * | findByName (const QString &name) const
virtual void | setNameFilter (const QString &filter)
const QString & | nameFilter () const
virtual void | setMimeFilter (const QStringList &mimeList)
void | setMimeExcludeFilter (const QStringList &mimeList)
virtual void | clearMimeFilter ()
const QStringList & | mimeFilters () const
bool | matchesFilter (const QString &name) const
bool | matchesMimeFilter (const QString &mime) const
void | setMainWindow (QWidget *window)
QWidget * | mainWindow ()
KFileItemList | items (WhichItems which=FilteredItems) const
KFileItemList | itemsForDir (const KURL &dir, WhichItems which=FilteredItems) const

## Protected Types

enum | Changes { NONE =0, NAME_FILTER =1, MIME_FILTER =2, DOT_FILES =4, DIR_ONLY_MODE =8 }

## Protected Member Functions

virtual bool | matchesFilter (const KFileItem *) const
virtual bool | matchesMimeFilter (const KFileItem *) const
virtual bool | doNameFilter (const QString &name, const QPtrList< QRegExp > &filters) const
virtual bool | doMimeFilter (const QString &mime, const QStringList &filters) const
bool | doMimeExcludeFilter (const QString &mimeExclude, const QStringList &filters) const
virtual bool | validURL (const KURL &) const
virtual void | handleError (KIO::Job *)
virtual void | virtual_hook (int id, void *data)

## Properties

bool | autoUpdate
bool | showingDotFiles
bool | dirOnlyMode
bool | autoErrorHandlingEnabled
QString | nameFilter
QStringList | mimeFilter

## Friends

class | KDirListerPrivate
class | KDirListerCache

## Detailed Description

The dir lister deals with the kiojob used to list and update a directory and has signals for the user of this class (e.g.

konqueror view or kdesktop) to create/destroy its items when asked.

This class is independent from the graphical representation of the dir (icon container, tree view, ...) and it stores the items (as KFileItems).

Typical usage :

- Create an instance.
- Connect to at least update, clear, newItem, and deleteItem.
- Call openURL - the signals will be called.
- Reuse the instance when opening a new url (openURL).
- Destroy the instance when not needed anymore (usually destructor).

Advanced usage : call openURL with _keep = true to list directories without forgetting the ones previously read (e.g. for a tree view)

Helper class for the kiojob used to list and update a directory.

Author
  Michael Brade brade.nosp@m.@kde.nosp@m..org

Definition at line 55 of file kdirlister.h.

## Member Enumeration Documentation

enum KDirLister::WhichItems

Used by items() and itemsForDir() to specify whether you want all items for a directory or just the filtered ones.

Definition at line 363 of file kdirlister.h.

## Constructor & Destructor Documentation

KDirLister::KDirLister | ( | bool | _delayedMimeTypes = `false` | ) |

Create a directory lister.

Parameters

  _delayedMimeTypes | if true, mime types will be fetched on demand. If false, they will always be fetched immediately

Definition at line 1822 of file kdirlister.cpp.

KDirLister::~KDirLister | ( |  | ) |

virtual

Destroy the directory lister.

Definition at line 1838 of file kdirlister.cpp.

## Member Function Documentation

bool KDirLister::autoErrorHandlingEnabled | ( |  | ) | const

Check whether auto error handling is enabled.

If enabled, it will show an error dialog to the user when an error occurs. It is turned on by default.

Returns
  true if auto error handling is enabled, false otherwise

See also
  setAutoErrorHandlingEnabled()

bool KDirLister::autoUpdate | ( |  | ) | const

Checks whether KDirWatch will automatically update directories.

This is enabled by default.

Returns
  true if KDirWatch is used to automatically update directories.

void KDirLister::canceled | ( |  | ) |

signal

Tell the view that the user canceled the listing.

No running jobs are left.

void KDirLister::canceled | ( | const KURL & | _url | ) |

signal

Tell the view that the listing of the directory `_url` was canceled.

There might be other running jobs left.

Parameters

  _url | the directory URL

void KDirLister::clear | ( |  | ) |

signal

Signal to clear all items.

It must always be connected to this signal to avoid doubled items!

void KDirLister::clear | ( | const KURL & | _url | ) |

signal

Signal to empty the directory `_url`.

It is only emitted if the lister is holding more than one directory.

Parameters

  _url | the directory that will be emptied

void KDirLister::clearMimeFilter | ( |  | ) |

virtual

Clears the mime based filter.

See also
  setMimeFilter

Definition at line 2115 of file kdirlister.cpp.

void KDirLister::completed | ( |  | ) |

signal

Tell the view that listing is finished.

There are no jobs running anymore.

void KDirLister::completed | ( | const KURL & | _url | ) |

signal

Tell the view that the listing of the directory `_url` is finished.

There might be other running jobs left.

Parameters

  _url | the directory URL

void KDirLister::deleteItem | ( | KFileItem * | _fileItem | ) |

signal

Signal an item to remove.

ATTENTION: if `_fileItem` == rootItem() the directory this lister is holding was deleted and you HAVE to release especially the rootItem() of this lister, otherwise your app will CRASH!! The clear() signals have been emitted already.

Parameters

  _fileItem | the fileItem to delete

const KURL::List & KDirLister::directories | ( |  | ) | const

Returns all URLs that are listed by this KDirLister.

This is only useful if you called openURL() with `_keep` == true, as it happens in a treeview, for example. (Note that the base url is included in the list as well, of course.)

Returns
  the list of all listed URLs

Since
  3.4

Definition at line 1936 of file kdirlister.cpp.

bool KDirLister::dirOnlyMode | ( |  | ) | const

Checks whether the KDirLister only lists directories or all files.

By default this option is disabled (all files will be shown).

Returns
  true if setDirOnlyMode(true) was called

bool KDirLister::doMimeFilter | ( | const QString & | mime,
|  | const QStringList & | filters
| ) |  | const

protected virtual

Called by the public matchesMimeFilter() to do the actual filtering.

Those methods may be reimplemented to customize filtering.

Parameters

  mime | the mime type to filter
  filters | the list of mime types to filter

Definition at line 2179 of file kdirlister.cpp.

bool KDirLister::doNameFilter | ( | const QString & | name,
|  | const QPtrList< QRegExp > & | filters
| ) |  | const

protected virtual

Called by the public matchesFilter() to do the actual filtering.

Those methods may be reimplemented to customize filtering.

Parameters

  name | the name to filter
  filters | a list of regular expressions for filtering

Definition at line 2170 of file kdirlister.cpp.

void KDirLister::emitChanges | ( |  | ) |

virtual

Actually emit the changes made with setShowingDotFiles, setDirOnlyMode, setNameFilter and setMimeFilter.

Definition at line 1941 of file kdirlister.cpp.

KFileItem * KDirLister::findByName | ( | const QString & | name | ) | const

virtual

Find an item by its name.

Parameters

  name | the item name

Returns
  the pointer to the KFileItem

Definition at line 2050 of file kdirlister.cpp.

KFileItem * KDirLister::findByURL | ( | const KURL & | _url | ) | const

virtual

Find an item by its URL.

Parameters

  _url | the item URL

Returns
  the pointer to the KFileItem

Definition at line 2045 of file kdirlister.cpp.

void KDirLister::handleError | ( | KIO::Job * | job | ) |

protected virtual

Reimplement to customize error handling.

Definition at line 2215 of file kdirlister.cpp.

void KDirLister::infoMessage | ( | const QString & | msg | ) |

signal

Emitted to display information about running jobs.

Examples of message are "Resolving host", "Connecting to host...", etc.

Parameters

  msg | the info message

bool KDirLister::isFinished | ( |  | ) | const

Returns true if no io operation is currently in progress.

Returns
  true if finished, false otherwise

Definition at line 2035 of file kdirlister.cpp.

KFileItemList KDirLister::items | ( | WhichItems | which = `FilteredItems` | ) | const

Returns the items listed for the current url().

This method will NOT start listing a directory, you should only call this when receiving the finished() signal.

The items in the KFileItemList are references to the items used by KDirLister, so e.g. an item gets destroyed when the deleteItem() signal is emitted.

Parameters

  which | specifies whether the returned list will contain all entries or only the ones that passed the nameFilter(), mimeFilter(), etc. Note that the latter causes iteration over all the items, filtering them. If this is too slow for you, use the newItems() signal, sending out filtered items in chunks.

Returns
  the items listed for the current url().

Since
  3.1

Definition at line 2468 of file kdirlister.cpp.

void KDirLister::itemsFilteredByMime | ( | const KFileItemList & | items | ) |

signal

Send a list of items filtered-out by mime-type.

Parameters

  items | the list of filtered items

KFileItemList KDirLister::itemsForDir | ( | const KURL & | dir,
|  | WhichItems | which = `FilteredItems`
| ) |  | const

Returns the items listed for the given `dir`.

This method will NOT start listing `dir`, you should only call this when receiving the finished() signal.

The items in the KFileItemList are references to the items used by KDirLister, so e.g. an item gets destroyed when the deleteItem() signal is emitted.

Parameters

  dir | specifies the url for which the items should be returned. This is only useful if you use KDirLister with multiple URLs i.e. using bool keep = true in openURL().
  which | specifies whether the returned list will contain all entries or only the ones that passed the nameFilter, mimeFilter, etc. Note that the latter causes iteration over all the items, filtering them. If this is too slow for you, use the newItems() signal, sending out filtered items in chunks.

Returns
  the items listed for `dir`.

Since
  3.1

Definition at line 2473 of file kdirlister.cpp.

QWidget * KDirLister::mainWindow | ( |  | ) |

Returns the main window associated with this object.

Returns
  the associated main window, or 0 if there is none

Since
  3.1

Definition at line 2463 of file kdirlister.cpp.

bool KDirLister::matchesFilter | ( | const QString & | name | ) | const

Checks whether `name` matches a filter in the list of name filters.

Returns
  true if `name` matches a filter in the list, otherwise false.

See also
  setNameFilter

Definition at line 2132 of file kdirlister.cpp.

bool KDirLister::matchesFilter | ( | const KFileItem * | item | ) | const

protected virtual

Called for every new item before emitting newItems().

You may reimplement this method in a subclass to implement your own filtering. The default implementation filters out ".." and everything not matching the name filter(s)

Returns
  true if the item is "ok". false if the item shall not be shown in a view, e.g. files not matching a pattern *.cpp ( KFileItem::isHidden())

See also
  matchesFilter
  setNameFilter

Definition at line 2144 of file kdirlister.cpp.

bool KDirLister::matchesMimeFilter | ( | const QString & | mime | ) | const

Checks whether `mime` matches a filter in the list of mime types.

Parameters

  mime | the mimetype to find in the filter list.

Returns
  true if `name` matches a filter in the list, otherwise false.

See also
  setMimeFilter.

Definition at line 2137 of file kdirlister.cpp.

bool KDirLister::matchesMimeFilter | ( | const KFileItem * | item | ) | const

protected virtual

Called for every new item before emitting newItems().

You may reimplement this method in a subclass to implement your own filtering. The default implementation filters out ".." and everything not matching the name filter(s)

Returns
  true if the item is "ok". false if the item shall not be shown in a view, e.g. files not matching a pattern *.cpp ( KFileItem::isHidden())

See also
  matchesMimeFilter
  setMimeFilter

Definition at line 2161 of file kdirlister.cpp.

const QStringList & KDirLister::mimeFilters | ( |  | ) | const

Returns the list of mime based filters, as set via setMimeFilter().

Returns
  the list of mime based filters. Empty, when no mime filter is set.

Definition at line 2127 of file kdirlister.cpp.

const QString& KDirLister::nameFilter | ( |  | ) | const

Returns the current name filter, as set via setNameFilter()

Returns
  the current name filter, can be QString::null if filtering is turned off

void KDirLister::newItems | ( | const KFileItemList & | items | ) |

signal

Signal new items.

Parameters

  items | a list of new items

bool KDirLister::openURL | ( | const KURL & | _url,
|  | bool | _keep = `false`,
|  | bool | _reload = `false`
| ) |  |

virtual

Run the directory lister on the given url.

This method causes KDirLister to emit all the items of `_url`, in any case. Depending on `_keep` either clear() or clear(const KURL &) will be emitted first.

The newItems() signal may be emitted more than once to supply you with KFileItems, up until the signal completed() is emitted (and isFinished() returns true).

Parameters

  _url | the directory URL.
  _keep | if true the previous directories aren't forgotten (they are still watched by kdirwatch and their items are kept for this KDirLister). This is useful for e.g. a treeview.
  _reload | indicates wether to use the cache (false) or to reread the directory from the disk. Use only when opening a dir not yet listed by this lister without using the cache. Otherwise use updateDirectory.

Returns
  true if successful, false otherwise (e.g. invalid `_url`)

Definition at line 1852 of file kdirlister.cpp.

void KDirLister::percent | ( | int | percent | ) |

signal

Progress signal showing the overall progress of the KDirLister.

This allows using a progress bar very easily. (see KProgress)

Parameters

  percent | the progress in percent

void KDirLister::processedSize | ( | KIO::filesize_t | size | ) |

signal

Regularly emitted to show the progress of this KDirLister.

Parameters

  size | the processed size in bytes

void KDirLister::redirection | ( | const KURL & | _url | ) |

signal

Signal a redirection.

Only emitted if there's just one directory to list, i.e. most probably openURL() has been called with `_keep` == `false`.

Parameters

  _url | the new URL

void KDirLister::redirection | ( | const KURL & | oldUrl,
|  | const KURL & | newUrl
| ) |  |

signal

Signal a redirection.

Parameters

  oldUrl | the original URL
  newUrl | the new URL

void KDirLister::refreshItems | ( | const KFileItemList & | items | ) |

signal

Signal an item to refresh (its mimetype/icon/name has changed).

Note: KFileItem::refresh has already been called on those items.

Parameters

  items | the items to refresh

KFileItem * KDirLister::rootItem | ( |  | ) | const

Returns the file item of the URL.

Returns
  the file item for url() itself (".")

Definition at line 2040 of file kdirlister.cpp.

void KDirLister::setAutoErrorHandlingEnabled | ( | bool | enable,
|  | QWidget * | parent
| ) |  |

Enable or disable auto error handling is enabled.

If enabled, it will show an error dialog to the user when an error occurs. It is turned on by default.

Parameters

  enable | true to enable auto error handling, false to disable
  parent | the parent widget for the error dialogs, can be 0 for top-level

See also
  autoErrorHandlingEnabled()

Definition at line 1925 of file kdirlister.cpp.

void KDirLister::setAutoUpdate | ( | bool | enable | ) |

virtual

Enable/disable automatic directory updating, when a directory changes (using KDirWatch).

Parameters

  enable | true to enable, false to disable

Definition at line 1883 of file kdirlister.cpp.

void KDirLister::setDirOnlyMode | ( | bool | dirsOnly | ) |

virtual

Call this to list only directories.

By default this option is disabled (all files will be shown).

Parameters

  dirsOnly | true to list only directories

Definition at line 1911 of file kdirlister.cpp.

void KDirLister::setMainWindow | ( | QWidget * | window | ) |

Pass the main window this object is associated with this is used for caching authentication data.

Parameters

  window | the window to associate with, 0 to disassociate

Since
  3.1

Definition at line 2458 of file kdirlister.cpp.

void KDirLister::setMimeExcludeFilter | ( | const QStringList & | mimeList | ) |

Filtering should be done with KFileFilter.

This will be implemented in a later revision of KDirLister. This method may be removed then.

Set mime-based exclude filter to only list items not matching the given mimetypes

NOTE: setting the filter does not automatically reload direcory. Also calling this function will not affect any named filter already set.

Parameters

  mimeList | a list of mime-types.

See also
  clearMimeFilter
  matchesMimeFilter

Since
  3.1

Definition at line 2105 of file kdirlister.cpp.

void KDirLister::setMimeFilter | ( | const QStringList & | mimeList | ) |

virtual

Set mime-based filter to only list items matching the given mimetypes.

NOTE: setting the filter does not automatically reload direcory. Also calling this function will not affect any named filter already set.

Parameters

  mimeList | a list of mime-types.

See also
  clearMimeFilter
  matchesMimeFilter

Definition at line 2091 of file kdirlister.cpp.

void KDirLister::setNameFilter | ( | const QString & | filter | ) |

virtual

Set a name filter to only list items matching this name, e.g.

"*.cpp".

You can set more than one filter by separating them with whitespace, e.g "*.cpp *.h". Note: the direcory is not automatically reloaded.

Parameters

  filter | the new filter, QString::null to disable filtering

See also
  matchesFilter

Definition at line 2065 of file kdirlister.cpp.

void KDirLister::setShowingDotFiles | ( | bool | _showDotFiles | ) |

virtual

Changes the "is viewing dot files" setting.

Calls updateDirectory() if setting changed. By default this option is disabled (hidden files will not be shown).

Parameters

  _showDotFiles | true to enable showing hidden files, false to disable

See also
  showingDotFiles()

Definition at line 1897 of file kdirlister.cpp.

bool KDirLister::showingDotFiles | ( |  | ) | const

Checks whether hidden files (files beginning with a dot) will be shown.

By default this option is disabled (hidden files will be not shown).

Returns
  true if dot files are shown, false otherwise

See also
  setShowingDotFiles()

void KDirLister::speed | ( | int | bytes_per_second | ) |

signal

Emitted to display information about the speed of the jobs.

Parameters

  bytes_per_second | the speed in bytes/s

void KDirLister::started | ( | const KURL & | _url | ) |

signal

Tell the view that we started to list `_url`.

NOTE: this does not imply that there is really a job running! I.e. KDirLister::jobs() may return an empty list. In this case the items are taken from the cache.

The view knows that openURL should start it, so it might seem useless, but the view also needs to know when an automatic update happens.

Parameters

  _url | the URL to list

void KDirLister::stop | ( |  | ) |

virtual

Stop listing all directories currently being listed.

Emits canceled() if there was at least one job running. Emits canceled( const KURL& ) for each stopped job if there are at least two dirctories being watched by KDirLister.

Definition at line 1866 of file kdirlister.cpp.

void KDirLister::stop | ( | const KURL & | _url | ) |

virtual

Stop listing the given directory.

Emits canceled() if the killed job was the last running one. Emits canceled( const KURL& ) for the killed job if there are at least two directories being watched by KDirLister. No signal is emitted if there was no job running for `_url`.

Parameters

  _url | the directory URL

Definition at line 1872 of file kdirlister.cpp.

void KDirLister::totalSize | ( | KIO::filesize_t | size | ) |

signal

Emitted when we know the size of the jobs.

Parameters

  size | the total size in bytes

void KDirLister::updateDirectory | ( | const KURL & | _dir | ) |

virtual

Update the directory `_dir`.

This method causes KDirLister to only emit the items of `_dir` that actually changed compared to the current state in the cache and updates the cache.

The current implementation calls updateDirectory automatically for local files, using KDirWatch (if autoUpdate() is true), but it might be useful to force an update manually.

Parameters

  _dir | the directory URL

Definition at line 2030 of file kdirlister.cpp.

const KURL & KDirLister::url | ( |  | ) | const

Returns the top level URL that is listed by this KDirLister.

It might be different from the one given with openURL() if there was a redirection. If you called openURL() with `_keep` == true this is the first url opened (e.g. in a treeview this is the root).

Returns
  the url used by this instance to list the files.

Definition at line 1931 of file kdirlister.cpp.

bool KDirLister::validURL | ( | const KURL & | _url | ) | const

protected virtual

Checks if an url is malformed or not and displays an error message if it is and autoErrorHandling is set to true.

Returns
  true if url is valid, otherwise false.

Definition at line 2210 of file kdirlister.cpp.

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

- kdirlister.h
- kdirlister.cpp

KDE Home | KDE Accessibility Home | Description of Access Keys