KDirLister Class Reference

from PyKDE4.kio import *

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, itemsAdded, and itemsDeleted.

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 OpenUrlFlag.Keep to list directories without forgetting the ones previously read (e.g. for a tree view)

Author:: Michael Brade <brade@kde.org>

Enumerations
Changes	{ NONE, NAME_FILTER, MIME_FILTER, DOT_FILES, DIR_ONLY_MODE }
OpenUrlFlag	{ NoFlags, Keep, Reload }
WhichItems	{ AllItems, FilteredItems }
Signals
	canceled ()
	canceled (KUrl _url)
	clear ()
	clear (KUrl _url)
	completed ()
	completed (KUrl _url)
	deleteItem (KFileItem _fileItem)
	infoMessage (QString msg)
	itemsAdded (KUrl directoryUrl, KFileItemList items)
	itemsDeleted (KFileItemList items)
	itemsFilteredByMime (KFileItemList items)
	newItems (KFileItemList items)
	percent (int percent)
	processedSize (long size)
	redirection (KUrl _url)
	redirection (KUrl oldUrl, KUrl newUrl)
	refreshItems ([(KFileItem,KFileItem)] items)
	speed (int bytes_per_second)
	started (KUrl _url)
	totalSize (long size)
Methods
	__init__ (self, QObject parent=0)
bool	autoErrorHandlingEnabled (self)
bool	autoUpdate (self)
	clearMimeFilter (self)
bool	delayedMimeTypes (self)
bool	dirOnlyMode (self)
KUrl.List	directories (self)
bool	doMimeFilter (self, QString mime, QStringList filters)
bool	doNameFilter (self, QString name, [QRegExp] filters)
	emitChanges (self)
KFileItem	findByName (self, QString name)
KFileItem	findByUrl (self, KUrl _url)
	handleError (self, KIO.Job a0)
bool	isFinished (self)
KFileItemList	items (self, KDirLister.WhichItems which=KDirLister.FilteredItems)
KFileItemList	itemsForDir (self, KUrl dir, KDirLister.WhichItems which=KDirLister.FilteredItems)
QWidget	mainWindow (self)
bool	matchesFilter (self, QString name)
bool	matchesFilter (self, KFileItem a0)
bool	matchesMimeFilter (self, QString mime)
bool	matchesMimeFilter (self, KFileItem a0)
QStringList	mimeFilters (self)
QString	nameFilter (self)
bool	openUrl (self, KUrl _url, KDirLister.OpenUrlFlags _flags=KDirLister.NoFlags)
KFileItem	rootItem (self)
	setAutoErrorHandlingEnabled (self, bool enable, QWidget parent)
	setAutoUpdate (self, bool enable)
	setDelayedMimeTypes (self, bool delayedMimeTypes)
	setDirOnlyMode (self, bool dirsOnly)
	setMainWindow (self, QWidget window)
	setMimeExcludeFilter (self, QStringList mimeList)
	setMimeFilter (self, QStringList mimeList)
	setNameFilter (self, QString filter)
	setShowingDotFiles (self, bool _showDotFiles)
bool	showingDotFiles (self)
	stop (self)
	stop (self, KUrl _url)
	updateDirectory (self, KUrl _dir)
KUrl	url (self)
Static Methods
KFileItem	cachedItemForUrl (KUrl url)

Signal Documentation

canceled ( )

Tell the view that the listing of the directory _url was canceled. There might be other running jobs left.

Parameters:

_url

the directory URL

Signal syntax:: QObject.connect(source, SIGNAL("canceled()"), target_slot)

canceled	(	KUrl	_url
	)

Tell the view that the listing of the directory _url was canceled. There might be other running jobs left.

Parameters:

_url

the directory URL

Signal syntax:: QObject.connect(source, SIGNAL("canceled(const KUrl&)"), target_slot)

clear ( )

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

Signal syntax:: QObject.connect(source, SIGNAL("clear()"), target_slot)

clear	(	KUrl	_url
	)

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

Signal syntax:: QObject.connect(source, SIGNAL("clear(const KUrl&)"), target_slot)

completed ( )

Tell the view that the listing of the directory _url is finished. There might be other running jobs left.

Parameters:

_url

the directory URL

Signal syntax:: QObject.connect(source, SIGNAL("completed()"), target_slot)

completed	(	KUrl	_url
	)

Tell the view that the listing of the directory _url is finished. There might be other running jobs left.

Parameters:

_url

the directory URL

Signal syntax:: QObject.connect(source, SIGNAL("completed(const KUrl&)"), target_slot)

deleteItem	(	KFileItem	_fileItem
	)

Signals that an item has been deleted

Deprecated:: Don't connect to this signal. Use itemsDeleted instead.

Parameters:

_fileItem

the fileItem to delete

Signal syntax:: QObject.connect(source, SIGNAL("deleteItem(const KFileItem&)"), target_slot)

infoMessage	(	QString	msg
	)

Emitted to display information about running jobs. Examples of message are "Resolving host", "Connecting to host...", etc.

Parameters:

msg

the info message

Signal syntax:: QObject.connect(source, SIGNAL("infoMessage(const QString&)"), target_slot)

itemsAdded	(	KUrl	directoryUrl,
		KFileItemList	items
	)

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

Signal syntax:: QObject.connect(source, SIGNAL("itemsAdded(const KUrl&, const KFileItemList&)"), target_slot)

itemsDeleted	(	KFileItemList	items
	)

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

Signal syntax:: QObject.connect(source, SIGNAL("itemsDeleted(const KFileItemList&)"), target_slot)

itemsFilteredByMime	(	KFileItemList	items
	)

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

Parameters:

items

the list of filtered items

Signal syntax:: QObject.connect(source, SIGNAL("itemsFilteredByMime(const KFileItemList&)"), target_slot)

newItems	(	KFileItemList	items
	)

Signal new items.

Parameters:

items

a list of new items

Signal syntax:: QObject.connect(source, SIGNAL("newItems(const KFileItemList&)"), target_slot)

percent	(	int	percent
	)

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

Signal syntax:: QObject.connect(source, SIGNAL("percent(int)"), target_slot)

processedSize	(	long	size
	)

Regularly emitted to show the progress of this KDirLister.

Parameters:

size

the processed size in bytes

Signal syntax:: QObject.connect(source, SIGNAL("processedSize(KIO::filesize_t)"), target_slot)

redirection	(	KUrl	_url
	)

Signal a redirection.

Parameters:

	oldUrl	the original URL
	newUrl	the new URL

Signal syntax:: QObject.connect(source, SIGNAL("redirection(const KUrl&)"), target_slot)

redirection	(	KUrl	oldUrl,
		KUrl	newUrl
	)

Signal a redirection.

Parameters:

	oldUrl	the original URL
	newUrl	the new URL

Signal syntax:: QObject.connect(source, SIGNAL("redirection(const KUrl&, const KUrl&)"), target_slot)

refreshItems	(	[(KFileItem,KFileItem)]	items
	)

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.

Signal syntax:: QObject.connect(source, SIGNAL("refreshItems(const QList>&)"), target_slot)

speed	(	int	bytes_per_second
	)

Emitted to display information about the speed of the jobs.

Parameters:

bytes_per_second

the speed in bytes/s

Signal syntax:: QObject.connect(source, SIGNAL("speed(int)"), target_slot)

started	(	KUrl	_url
	)

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

Signal syntax:: QObject.connect(source, SIGNAL("started(const KUrl&)"), target_slot)

totalSize	(	long	size
	)

Emitted when we know the size of the jobs.

Parameters:

size

the total size in bytes

Signal syntax:: QObject.connect(source, SIGNAL("totalSize(KIO::filesize_t)"), target_slot)

Method Documentation

__init__	(	self,
		QObject	parent=0
	)

Create a directory lister.

bool autoErrorHandlingEnabled ( self )

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

Checks whether KDirWatch will automatically update directories. This is enabled by default.

Returns:: true if KDirWatch is used to automatically update directories.

clearMimeFilter ( self )

Clears the mime based filter.

You need to call emitChanges() afterwards.

See also:: setMimeFilter

bool delayedMimeTypes ( self )

Returns:: true if the "delayed mimetypes" feature was enabled

See also:: setDelayedMimeTypes

bool dirOnlyMode ( self )

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

KUrl.List directories ( self )

Returns all URLs that are listed by this KDirLister. This is only useful if you called openUrl() with OpenUrlFlag.Keep, 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

bool doMimeFilter	(	self,
		QString	mime,
		QStringList	filters
	)

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

bool doNameFilter	(	self,
		QString	name,
		[QRegExp]	filters
	)

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

emitChanges ( self )

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

KFileItem findByName	(	self,
		QString	name
	)

Find an item by its name.

Parameters:

name

the item name

Returns:: the KFileItem

KFileItem findByUrl	(	self,
		KUrl	_url
	)

Find an item by its URL.

Parameters:

_url

the item URL

Returns:: the KFileItem

handleError	(	self,
		KIO.Job	a0
	)

Reimplement to customize error handling

bool isFinished ( self )

Returns true if no io operation is currently in progress.

Returns:: true if finished, false otherwise

KFileItemList items	(	self,
		KDirLister.WhichItems	which=KDirLister.FilteredItems
	)

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

KFileItemList itemsForDir	(	self,
		KUrl	dir,
		KDirLister.WhichItems	which=KDirLister.FilteredItems
	)

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 OpenUrlFlag.Keep 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.

QWidget mainWindow ( self )

Returns the main window associated with this object.

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

bool matchesFilter	(	self,
		QString	name
	)

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

See also:: setNameFilter

bool matchesFilter	(	self,
		KFileItem	a0
	)

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

See also:: setNameFilter

bool matchesMimeFilter	(	self,
		QString	mime
	)

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

See also:: setMimeFilter

bool matchesMimeFilter	(	self,
		KFileItem	a0
	)

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

See also:: setMimeFilter

QStringList mimeFilters ( self )

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.

QString nameFilter ( self )

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

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

bool openUrl	(	self,
		KUrl	_url,
		KDirLister.OpenUrlFlags	_flags=KDirLister.NoFlags
	)

Run the directory lister on the given url.

This method causes KDirLister to emit _all_ the items of _url, in any case. Depending on _flags, 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)

KFileItem rootItem ( self )

Returns the file item of the URL.

Can return an empty KFileItem.

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

setAutoErrorHandlingEnabled	(	self,
		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()

setAutoUpdate	(	self,
		bool	enable
	)

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

Parameters:

enable

true to enable, false to disable

setDelayedMimeTypes	(	self,
		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).

setDirOnlyMode	(	self,
		bool	dirsOnly
	)

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

setMainWindow	(	self,
		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

setMimeExcludeFilter	(	self,
		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

See also:: matchesMimeFilter

Internal:

setMimeFilter	(	self,
		QStringList	mimeList
	)

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

See also:: matchesMimeFilter

setNameFilter	(	self,
		QString	filter
	)

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

setShowingDotFiles	(	self,
		bool	_showDotFiles
	)

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

bool showingDotFiles ( self )

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

stop ( self )

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

stop	(	self,
		KUrl	_url
	)

Stop listing the given directory.

Parameters:

_url

the directory URL

updateDirectory	(	self,
		KUrl	_dir
	)

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

KUrl url ( self )

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 OpenUrlFlag.Keep 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.

Static Method Documentation

KFileItem cachedItemForUrl	(	KUrl	url
	)

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

Enumeration Documentation

Changes

Enumerator:

NONE = 0
NAME_FILTER = 1
MIME_FILTER = 2
DOT_FILES = 4
DIR_ONLY_MODE = 8

OpenUrlFlag

Enumerator:

NoFlags = 0x0
Keep = 0x1
Reload = 0x2

WhichItems

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

Enumerator:

AllItems = 0
FilteredItems = 1

KDirLister Class Reference

Detailed Description

Enumerations

Signals

Methods

Static Methods

Signal Documentation

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules