---

KDirLister Class Reference

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

#include <kdirlister.h>

Inheritance diagram for KDirLister:

List of all members.

Public Types
enum	WhichItems
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 Methods
	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
virtual void	emitChanges ()
virtual void	updateDirectory (const KURL &_dir)
bool	isFinished () const
KFileItem *	rootItem () const
virtual KFileItem *	findByURL (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 Methods
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
virtual bool	validURL (const KURL &) const
virtual void	handleError (KIO::Job *)

---

Detailed Description

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

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)

Definition at line 54 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 350 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

virtual KDirLister::~KDirLister (    )  [virtual]

Destroy the directory lister.

---

Member Function Documentation

bool KDirLister::autoErrorHandlingEnabled (    )

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

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 (  const KURL &    _url )  [signal]

Tell the view that the listing of the directory _url was canceled. There might be other running jobs left. This signal is only emitted if KDirLister is watching more than one directory. Parameters: _url  the directory URL

void KDirLister::canceled (    )  [signal]

Tell the view that the user canceled the listing. No running jobs are left.

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::clear (    )  [signal]

Signal to clear all items. It must always be connected to this signal to avoid doubled items!

virtual void KDirLister::clearMimeFilter (    )  [virtual]

Clears the mime based filter. See also: setMimeFilter

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. This signal is only emitted if KDirLister is watching more than one directory. Parameters: _url  the directory URL

void KDirLister::completed (    )  [signal]

Tell the view that listing is finished. There are no jobs running anymore.

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: the  fileItem to delete

bool KDirLister::dirOnlyMode (    )

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

virtual 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

virtual 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 filers  a list of regular expressions for filtering

virtual void KDirLister::emitChanges (    )  [virtual]

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

virtual 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

virtual 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

virtual void KDirLister::handleError (  KIO::Job *    )  [protected, virtual]

Reimplement to customize error handling

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

Returns true if no io operation is currently in progress. Returns: true if finished, false otherwise

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

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 the current url(). Since: 3.1

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

virtual bool KDirLister::matchesFilter (  const KFileItem *    )  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

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

virtual bool KDirLister::matchesMimeFilter (  const KFileItem *    )  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

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.

const QStringList& KDirLister::mimeFilters (    )

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. Referenced by KDirOperator::mimeFilter().

const QString& KDirLister::nameFilter (    )

Returns the current name filter, as set via setNameFilter() Returns: the current name filter, can be QString::null if filtering is turned off Referenced by KDirOperator::nameFilter().

void KDirLister::newItems (  const KFileItemList &    items )  [signal]

Signal new items. Parameters: items  a list of new items

virtual 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)

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 &    oldUrl, const KURL &    newUrl )  [signal]

Signal a redirection. Parameters: oldUrl  the original URL newUrl  the new URL

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 @p_keep == false. Parameters: _url  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 (    )

Returns the file item of the URL. Returns: the file item for url() itself (".")

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

virtual 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

virtual 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

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

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

virtual 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

virtual 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: filer  the new filter, QString::null to disable filtering See also: matchesFilter

virtual 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()

bool KDirLister::showingDotFiles (    )

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

virtual 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

virtual 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.

void KDirLister::totalSize (  KIO::filesize_t    size )  [signal]

Emitted when we know the size of the jobs. Parameters: size  the total size in bytes

virtual 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

const KURL& KDirLister::url (    )

Returns the 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 (in e.g. a treeview this is the root). Returns: the url used by this instance to list the files.

virtual bool KDirLister::validURL (  const KURL &    )  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.

---

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

• kdirlister.h

---