kio Library API Documentation

KDirLister Class Reference

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. Helper class for the kiojob used to list and update a directory. More...

#include <kdirlister.h>

Inheritance diagram for KDirLister:

QObject KFileTreeBranch List of all members.

Public Types

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


Signals

void started (const KURL &_url)
 Tell the view that we started to list _url.

void completed ()
 Tell the view that listing is finished.

void completed (const KURL &_url)
 Tell the view that the listing of the directory _url is finished.

void canceled ()
 Tell the view that the user canceled the listing.

void canceled (const KURL &_url)
 Tell the view that the listing of the directory _url was canceled.

void redirection (const KURL &_url)
 Signal a redirection.

void redirection (const KURL &oldUrl, const KURL &newUrl)
 Signal a redirection.

void clear ()
 Signal to clear all items.

void clear (const KURL &_url)
 Signal to empty the directory _url.

void newItems (const KFileItemList &items)
 Signal new items.

void itemsFilteredByMime (const KFileItemList &items)
 Send a list of items filtered-out by mime-type.

void deleteItem (KFileItem *_fileItem)
 Signal an item to remove.

void refreshItems (const KFileItemList &items)
 Signal an item to refresh (its mimetype/icon/name has changed) Note: KFileItem::refresh has already been called on those items.

void infoMessage (const QString &msg)
 Emitted to display information about running jobs.

void percent (int percent)
 Progress signal showing the overall progress of the KDirLister.

void totalSize (KIO::filesize_t size)
 Emitted when we know the size of the jobs.

void processedSize (KIO::filesize_t size)
 Regularly emitted to show the progress of this KDirLister.

void speed (int bytes_per_second)
 Emitted to display information about the speed of the jobs.


Public Methods

 KDirLister (bool _delayedMimeTypes=false)
 Create a directory lister.

virtual ~KDirLister ()
 Destroy the directory lister.

virtual bool openURL (const KURL &_url, bool _keep=false, bool _reload=false)
 Run the directory lister on the given url.

virtual void stop ()
 Stop listing all directories currently being listed.

virtual void stop (const KURL &_url)
 Stop listing the given directory.

bool autoUpdate () const
virtual void setAutoUpdate (bool enable)
 Enable/disable automatic directory updating, when a directory changes (using KDirWatch).

bool autoErrorHandlingEnabled () const
 Error handling.

bool showingDotFiles () const
virtual void setShowingDotFiles (bool _showDotFiles)
 Changes the "is viewing dot files" setting.

bool dirOnlyMode () const
virtual void setDirOnlyMode (bool dirsOnly)
 Call this with dirsOnly == true to list only directories.

const KURLurl () const
virtual void emitChanges ()
 actually emit the changes made with setShowingDotFiles, setDirOnlyMode, setNameFilter and setMimeFilter.

virtual void updateDirectory (const KURL &_dir)
 Update the directory _dir.

bool isFinished () const
 Returns true if no io operation is currently in progress.

KFileItemrootItem () const
virtual KFileItemfindByURL (const KURL &_url) const
 Find an item by its URL.

virtual KFileItemfindByName (const QString &name) const
 Find an item by its name.

virtual void setNameFilter (const QString &)
 Set a name filter to only list items matching this name, e.g.

const QStringnameFilter () const
virtual void setMimeFilter (const QStringList &)
 Set mime-based filter to only list items matching the given mimetypes.

void setMimeExcludeFilter (const QStringList &)
 Filtering should be done with KFileFilter.

virtual void clearMimeFilter ()
 Clears the mime based filter.

const QStringListmimeFilters () const
bool matchesFilter (const QString &name) const
bool matchesMimeFilter (const QString &mime) const
void setMainWindow (QWidget *window)
 Pass the main window this object is associated with this is used for caching authentication data
Since:
3.1.


QWidgetmainWindow ()
 Returns the main window associated with this object.

KFileItemList items (WhichItems which=FilteredItems) const
 Returns the items listed for the current url().

KFileItemList itemsForDir (const KURL &dir, WhichItems which=FilteredItems) const
 Returns the items listed for the given dir.


Protected Methods

virtual bool matchesFilter (const KFileItem *) const
 Called for every new item before emitting newItems().

virtual bool doNameFilter (const QString &name, const QPtrList< QRegExp > &filters) const
 Called by the public matchesFilter/matchesMimeFilter to do the actual filtering.

virtual bool validURL (const KURL &) const
 Checks if an url is malformed or not and displays an error message if it is and autoErrorHandling is set to true.

virtual void handleError (KIO::Job *)
 Reimplement to customize error handling.


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. Helper class for the kiojob used to list and update a directory.

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 309 of file kdirlister.h.


Constructor & Destructor Documentation

KDirLister::KDirLister bool    _delayedMimeTypes = false
 

Create a directory lister.

Definition at line 1479 of file kdirlister.cpp.

References canceled(), completed(), QObject::connect(), setAutoUpdate(), setDirOnlyMode(), and setShowingDotFiles().

KDirLister::~KDirLister   [virtual]
 

Destroy the directory lister.

Definition at line 1500 of file kdirlister.cpp.

References stop().


Member Function Documentation

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.

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

Definition at line 1511 of file kdirlister.cpp.

References emitChanges(), KURL::prettyURL(), and validURL().

Referenced by KFileTreeBranch::populate(), KDirOperator::rereadDir(), and KDirOperator::setURL().

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 1530 of file kdirlister.cpp.

Referenced by KDirOperator::close(), and ~KDirLister().

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 1536 of file kdirlister.cpp.

References KURL::prettyURL().

bool KDirLister::autoUpdate  
 

Returns:
whether KDirWatch is used to automatically update directories. This is enabled by default.

Definition at line 1542 of file kdirlister.cpp.

void KDirLister::setAutoUpdate bool    enable [virtual]
 

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

Definition at line 1547 of file kdirlister.cpp.

Referenced by KDirLister(), and KDirOperator::setDirLister().

bool KDirLister::autoErrorHandlingEnabled  
 

Error handling.

Definition at line 1584 of file kdirlister.cpp.

bool KDirLister::showingDotFiles  
 

Returns:
whether dotfiles are shown

Definition at line 1556 of file kdirlister.cpp.

void KDirLister::setShowingDotFiles bool    _showDotFiles [virtual]
 

Changes the "is viewing dot files" setting.

Calls updateDirectory() if setting changed

Definition at line 1561 of file kdirlister.cpp.

Referenced by KDirLister(), KFileTreeBranch::KFileTreeBranch(), and KDirOperator::readConfig().

bool KDirLister::dirOnlyMode  
 

Returns:
true if setDirOnlyMode(true) was called

Definition at line 1570 of file kdirlister.cpp.

void KDirLister::setDirOnlyMode bool    dirsOnly [virtual]
 

Call this with dirsOnly == true to list only directories.

Definition at line 1575 of file kdirlister.cpp.

Referenced by KDirLister(), KFileTreeView::setDirOnlyMode(), and KDirOperator::setMode().

const KURL & KDirLister::url  
 

Returns:
the url used by this instance to list the files, with _keep == true, this is the first url opened (in e.g. a treeview this is the root). It might be different from the one given with openURL() or setURL() if there was a redirection.

Definition at line 1595 of file kdirlister.cpp.

Referenced by items().

void KDirLister::emitChanges   [virtual]
 

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

Definition at line 1600 of file kdirlister.cpp.

References QPtrListIterator< KFileItem >::current(), deleteItem(), doNameFilter(), and KGlobal::staticQString().

Referenced by openURL(), and KDirOperator::updateDir().

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 1689 of file kdirlister.cpp.

bool KDirLister::isFinished  
 

Returns true if no io operation is currently in progress.

Definition at line 1694 of file kdirlister.cpp.

KFileItem * KDirLister::rootItem  
 

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

Definition at line 1699 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 1704 of file kdirlister.cpp.

Referenced by KFileTreeBranch::findTVIByURL().

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 1709 of file kdirlister.cpp.

Referenced by KDirOperator::setCurrentItem().

void KDirLister::setNameFilter const QString   [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". Call setNameFilter( QString::null ) to disable filtering. Note: the direcory is not automatically reloaded.

See also:
matchesFilter

Definition at line 1724 of file kdirlister.cpp.

References QStringList::split().

Referenced by KDirOperator::clearFilter(), and KDirOperator::setNameFilter().

const QString & KDirLister::nameFilter  
 

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

Definition at line 1745 of file kdirlister.cpp.

Referenced by KDirOperator::nameFilter().

void KDirLister::setMimeFilter const QStringList   [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.

See also:
clearMimeFilter , matchesMimeFilter
Parameters:
a  list of mime-types.

Definition at line 1750 of file kdirlister.cpp.

Referenced by KDirOperator::setMimeFilter().

void KDirLister::setMimeExcludeFilter const QStringList  
 

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.

See also:
clearMimeFilter , matchesMimeFilter
Parameters:
a  list of mime-types.
Since:
3.1

Definition at line 1759 of file kdirlister.cpp.

void KDirLister::clearMimeFilter   [virtual]
 

Clears the mime based filter.

See also:
setMimeFilter

Definition at line 1769 of file kdirlister.cpp.

Referenced by KDirOperator::clearFilter().

const QStringList & KDirLister::mimeFilters  
 

Returns:
the list of mime based filters, as set via setMimeFilter(). Empty, when no mime filter is set.

Definition at line 1781 of file kdirlister.cpp.

Referenced by KDirOperator::mimeFilter().

bool KDirLister::matchesFilter const QString   name const
 

Returns:
true if name matches a filter in the list, otherwise false.
See also:
setNameFilter

Definition at line 1786 of file kdirlister.cpp.

References doNameFilter().

Referenced by itemsForDir(), and matchesFilter().

bool KDirLister::matchesMimeFilter const QString   mime const
 

Returns:
true if name matches a filter in the list, otherwise false.
See also:
setNameFilter.
Parameters:
mime  the mimetype to find in the filter list.

Definition at line 1791 of file kdirlister.cpp.

Referenced by itemsForDir().

void KDirLister::setMainWindow QWidget   window
 

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

Since:
3.1.

Definition at line 2064 of file kdirlister.cpp.

QWidget * KDirLister::mainWindow  
 

Returns the main window associated with this object.

Since:
3.1

Definition at line 2069 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 2074 of file kdirlister.cpp.

References itemsForDir(), and url().

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

Definition at line 2079 of file kdirlister.cpp.

References QPtrList< KFileItem >::append(), QPtrListIterator< KFileItem >::current(), KFileItem::isDir(), matchesFilter(), and matchesMimeFilter().

Referenced by items().

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.

Referenced by KFileTreeBranch::KFileTreeBranch().

void KDirLister::completed   [signal]
 

Tell the view that listing is finished.

There are no jobs running anymore.

Referenced by KDirLister(), and KFileTreeBranch::KFileTreeBranch().

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::canceled   [signal]
 

Tell the view that the user canceled the listing.

No running jobs are left.

Referenced by KDirLister(), and KFileTreeBranch::KFileTreeBranch().

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::redirection const KURL   _url [signal]
 

Signal a redirection.

Only emitted if there's just one directory to list, i.e. most probably _keep == false

Referenced by KFileTreeBranch::KFileTreeBranch().

void KDirLister::redirection const KURL   oldUrl,
const KURL   newUrl
[signal]
 

Signal a redirection.

void KDirLister::clear   [signal]
 

Signal to clear all items.

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

Referenced by KFileTreeBranch::KFileTreeBranch().

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.

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

Signal new items.

Referenced by KFileTreeBranch::KFileTreeBranch().

void KDirLister::itemsFilteredByMime const KFileItemList &    items [signal]
 

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

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.

Referenced by emitChanges(), and KFileTreeBranch::KFileTreeBranch().

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.

void KDirLister::infoMessage const QString   msg [signal]
 

Emitted to display information about running jobs.

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

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)

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

Emitted when we know the size of the jobs.

void KDirLister::processedSize KIO::filesize_t    size [signal]
 

Regularly emitted to show the progress of this KDirLister.

void KDirLister::speed int    bytes_per_second [signal]
 

Emitted to display information about the speed of the jobs.

bool KDirLister::matchesFilter const KFileItem   const [protected, virtual]
 

Called for every new item before emitting newItems().

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()) 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)
See also:
matchesFilter , setNameFilter

Definition at line 1798 of file kdirlister.cpp.

References KFileItem::isDir(), matchesFilter(), KGlobal::staticQString(), and KFileItem::text().

bool KDirLister::doNameFilter const QString   name,
const QPtrList< QRegExp > &    filters
const [protected, virtual]
 

Called by the public matchesFilter/matchesMimeFilter to do the actual filtering.

Those methods may be reimplemented to customize filtering.

Definition at line 1821 of file kdirlister.cpp.

References QPtrListIterator::current().

Referenced by emitChanges(), and matchesFilter().

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.

Definition at line 1857 of file kdirlister.cpp.

References KMessageBox::error(), KURL::isMalformed(), and KURL::prettyURL().

Referenced by openURL().

void KDirLister::handleError KIO::Job   [protected, virtual]
 

Reimplement to customize error handling.

Definition at line 1874 of file kdirlister.cpp.

References KIO::Job::showErrorDialog().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:21:34 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001