• Skip to content
  • Skip to link menu
KDE 4.2 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KIO

KDirLister Class Reference

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

#include <kdirlister.h>

Inheritance diagram for KDirLister:

Inheritance graph
[legend]

List of all members.


Public Types

enum  OpenUrlFlag { NoFlags = 0x0, Keep = 0x1, Reload = 0x2 }
enum  WhichItems { AllItems = 0, FilteredItems = 1 }

Signals

void canceled (const KUrl &_url)
void canceled ()
void clear (const KUrl &_url)
void clear ()
void completed (const KUrl &_url)
void completed ()
void deleteItem (const KFileItem &_fileItem)
void infoMessage (const QString &msg)
void itemsAdded (const KUrl &directoryUrl, const KFileItemList &items)
void itemsDeleted (const KFileItemList &items)
void itemsFilteredByMime (const KFileItemList &items)
void newItems (const KFileItemList &items)
void percent (int percent)
void processedSize (KIO::filesize_t size)
void redirection (const KUrl &oldUrl, const KUrl &newUrl)
void redirection (const KUrl &_url)
void refreshItems (const QList< QPair< KFileItem, KFileItem > > &items)
void speed (int bytes_per_second)
void started (const KUrl &_url)
void totalSize (KIO::filesize_t size)

Public Member Functions

bool autoErrorHandlingEnabled () const
bool autoUpdate () const
virtual void clearMimeFilter ()
bool delayedMimeTypes () const
KUrl::List directories () const
bool dirOnlyMode () const
virtual void emitChanges ()
virtual KFileItem findByName (const QString &name) const
virtual KFileItem findByUrl (const KUrl &_url) const
bool isFinished () const
KFileItemList items (WhichItems which=FilteredItems) const
KFileItemList itemsForDir (const KUrl &dir, WhichItems which=FilteredItems) const
 KDirLister (QObject *parent=0)
QWidget * mainWindow ()
bool matchesFilter (const QString &name) const
bool matchesMimeFilter (const QString &mime) const
QStringList mimeFilters () const
QString nameFilter () const
virtual bool openUrl (const KUrl &_url, OpenUrlFlags _flags=NoFlags)
KFileItem rootItem () const
void setAutoErrorHandlingEnabled (bool enable, QWidget *parent)
virtual void setAutoUpdate (bool enable)
void setDelayedMimeTypes (bool delayedMimeTypes)
virtual void setDirOnlyMode (bool dirsOnly)
void setMainWindow (QWidget *window)
void setMimeExcludeFilter (const QStringList &mimeList)
virtual void setMimeFilter (const QStringList &mimeList)
virtual void setNameFilter (const QString &filter)
virtual void setShowingDotFiles (bool _showDotFiles)
bool showingDotFiles () const
virtual void stop (const KUrl &_url)
virtual void stop ()
virtual void updateDirectory (const KUrl &_dir)
KUrl url () const
virtual ~KDirLister ()

Static Public Member Functions

static KFileItem cachedItemForUrl (const KUrl &url)

Protected Types

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

Protected Member Functions

virtual bool doMimeFilter (const QString &mime, const QStringList &filters) const
virtual bool doNameFilter (const QString &name, const QList< QRegExp > &filters) const
virtual void handleError (KIO::Job *)
virtual bool matchesFilter (const KFileItem &) const
virtual bool matchesMimeFilter (const KFileItem &) const

Properties

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

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)

Author:
Michael Brade <brade@kde.org>

Definition at line 57 of file kdirlister.h.


Member Enumeration Documentation

enum KDirLister::Changes [protected]

Deprecated:
and unused, ignore this
Enumerator:
NONE 
NAME_FILTER 
MIME_FILTER 
DOT_FILES 
DIR_ONLY_MODE 

Definition at line 598 of file kdirlister.h.

enum KDirLister::OpenUrlFlag

Enumerator:
NoFlags  No additional flags specified.
Keep  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 whether to use the cache 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.

Definition at line 72 of file kdirlister.h.

enum KDirLister::WhichItems

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

Enumerator:
AllItems 
FilteredItems 

Definition at line 391 of file kdirlister.h.


Constructor & Destructor Documentation

KDirLister::KDirLister ( QObject *  parent = 0  ) 

Create a directory lister.

Definition at line 1797 of file kdirlister.cpp.

KDirLister::~KDirLister (  )  [virtual]

Destroy the directory lister.

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

KFileItem KDirLister::cachedItemForUrl ( const KUrl &  url  )  [static]

Return the KFileItem for the given URL, if we listed it recently and it's still in the cache - which is always the case if a directory view is currently showing this item.

If not, then it might be in the cache, or it might not, in which case you get a null KFileItem. If you really need a KFileItem for this URL in all cases, then use KIO::stat() instead.

Since:
4.2

Definition at line 2517 of file kdirlister.cpp.

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

Make sure to connect to this signal to avoid doubled items.

void KDirLister::clearMimeFilter (  )  [virtual]

Clears the mime based filter.

You need to call emitChanges() afterwards.

See also:
setMimeFilter

Definition at line 2043 of file kdirlister.cpp.

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

Tell the view that listing is finished.

There are no jobs running anymore.

bool KDirLister::delayedMimeTypes (  )  const

Returns:
true if the "delayed mimetypes" feature was enabled
See also:
setDelayedMimeTypes

void KDirLister::deleteItem ( const KFileItem &  _fileItem  )  [signal]

Signals that an item has been deleted.

Parameters:
_fileItem the fileItem to delete

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

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

bool KDirLister::doNameFilter ( const QString &  name,
const QList< 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 2093 of file kdirlister.cpp.

void KDirLister::emitChanges (  )  [virtual]

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

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

Definition at line 1993 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 KFileItem

Definition at line 1983 of file kdirlister.cpp.

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

Reimplement to customize error handling.

Definition at line 2134 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 1973 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().

Definition at line 2429 of file kdirlister.cpp.

void KDirLister::itemsAdded ( const KUrl &  directoryUrl,
const KFileItemList &  items 
) [signal]

Signal that new items were found during directory listing.

Alternative signal emitted at the same time as newItems(), but itemsAdded also passes the url of the parent directory.

Parameters:
items a list of new items
Since:
4.2

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

Signal that items have been deleted Note that this signal is newer than deleteItem, so when items are deleted, both signals are emitted, for compatibility reasons.

Since:
4.1.2
Parameters:
items the list of deleted items

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.

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

Definition at line 2424 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 2068 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 2055 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 2084 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 2060 of file kdirlister.cpp.

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

QString KDirLister::nameFilter (  )  const

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

Returns:
the current name filter, can be QString() 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,
OpenUrlFlags  _flags = NoFlags 
) [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.
_flags whether to keep previous directories, and whether to reload, see OpenUrlFlags
Returns:
true if successful, false otherwise (e.g. invalid _url)

Definition at line 1824 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 QProgressBar)

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 _keep == false.

Parameters:
_url the new URL

void KDirLister::refreshItems ( const QList< QPair< KFileItem, KFileItem > > &  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. This is a list of pairs, where the first item in the pair is the OLD item, and the second item is the NEW item. This allows to track which item has changed, especially after a renaming.

KFileItem KDirLister::rootItem (  )  const

Returns the file item of the URL.

Can return an empty KFileItem.

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

Definition at line 1978 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 1892 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 1850 of file kdirlister.cpp.

void KDirLister::setDelayedMimeTypes ( bool  delayedMimeTypes  ) 

Delayed mimetypes feature: If enabled, mime types will be fetched on demand, which leads to a faster initial directory listing, where icons get progressively replaced with the correct one while KMimeTypeResolver is going through the items with unknown or imprecise mimetype (e.g.

files with no extension or an unknown extension).

Definition at line 2463 of file kdirlister.cpp.

void KDirLister::setDirOnlyMode ( bool  dirsOnly  )  [virtual]

Call this to list only directories.

You need to call emitChanges() afterwards. By default this option is disabled (all files will be shown).

Parameters:
dirsOnly true to list only directories

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

Definition at line 2419 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 directory. Also calling this function will not affect any named filter already set.

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

matchesMimeFilter

For internal use only.

Definition at line 2033 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 directory. Also calling this function will not affect any named filter already set.

You need to call emitChanges() afterwards.

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

matchesMimeFilter

Definition at line 2021 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 directory is not automatically reloaded. You need to call emitChanges() afterwards.

Parameters:
filter the new filter, QString() to disable filtering
See also:
matchesFilter

Definition at line 2001 of file kdirlister.cpp.

void KDirLister::setShowingDotFiles ( bool  _showDotFiles  )  [virtual]

Changes the "is viewing dot files" setting.

You need to call emitChanges() afterwards. 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 1864 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 ( 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 1840 of file kdirlister.cpp.

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

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


Property Documentation

bool KDirLister::autoErrorHandlingEnabled [read]

Definition at line 66 of file kdirlister.h.

bool KDirLister::autoUpdate [read, write]

Definition at line 63 of file kdirlister.h.

bool KDirLister::delayedMimeTypes [read, write]

Definition at line 67 of file kdirlister.h.

bool KDirLister::dirOnlyMode [read, write]

Definition at line 65 of file kdirlister.h.

QStringList KDirLister::mimeFilter [read, write]

Definition at line 69 of file kdirlister.h.

QString KDirLister::nameFilter [read, write]

Definition at line 68 of file kdirlister.h.

bool KDirLister::showingDotFiles [read, write]

Definition at line 64 of file kdirlister.h.


The documentation for this class was generated from the following files:
  • kdirlister.h
  • kdirlister.cpp

KIO

Skip menu "KIO"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.7
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal