• Skip to content
  • Skip to link menu
Trinity API Reference
  • Trinity API Reference
  • tdeio/tdeio
 

tdeio/tdeio

Public Types | Signals | Public Member Functions | Protected Types | Protected Member Functions | Friends | List of all members
KDirLister Class Reference

#include <kdirlister.h>

Inherits TQObject.

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 TQString &msg)
 
void percent (int percent)
 
void totalSize (TDEIO::filesize_t size)
 
void processedSize (TDEIO::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, TQWidget *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 TQString &name) const
 
virtual void setNameFilter (const TQString &filter)
 
const TQString & nameFilter () const
 
virtual void setMimeFilter (const TQStringList &mimeList)
 
void setMimeExcludeFilter (const TQStringList &mimeList)
 
virtual void clearMimeFilter ()
 
const TQStringList & mimeFilters () const
 
bool matchesFilter (const TQString &name) const
 
bool matchesMimeFilter (const TQString &mime) const
 
void setMainWindow (TQWidget *window)
 
TQWidget * mainWindow ()
 
KFileItemList items (WhichItems which=FilteredItems) const
 
KFileItemList itemsForDir (const KURL &dir, WhichItems which=FilteredItems) const
 
void emitCompleted (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 matchesFilter (const KFileItem *) const
 
virtual bool matchesMimeFilter (const KFileItem *) const
 
virtual bool doNameFilter (const TQString &name, const TQPtrList< TQRegExp > &filters) const
 
virtual bool doMimeFilter (const TQString &mime, const TQStringList &filters) const
 
bool doMimeExcludeFilter (const TQString &mimeExclude, const TQStringList &filters) const
 
virtual bool validURL (const KURL &) const
 
virtual void handleError (TDEIO::Job *)
 
virtual void virtual_hook (int id, void *data)
 

Friends

class KDirListerPrivate
 
class KDirListerCache
 

Detailed Description

The dir lister deals with the tdeiojob 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 tdeiojob 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
_delayedMimeTypesif true, mime types will be fetched on demand. If false, they will always be fetched immediately

Definition at line 1907 of file kdirlister.cpp.

KDirLister::~KDirLister ( )
virtual

Destroy the directory lister.

Definition at line 1923 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()

Definition at line 2046 of file kdirlister.cpp.

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.

Definition at line 2004 of file kdirlister.cpp.

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
_urlthe 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
_urlthe directory that will be emptied
void KDirLister::clearMimeFilter ( )
virtual

Clears the mime based filter.

See also
setMimeFilter

Definition at line 2246 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
_urlthe 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
_fileItemthe 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 2062 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

Definition at line 2032 of file kdirlister.cpp.

bool KDirLister::doMimeFilter ( const TQString &  mime,
const TQStringList &  filters 
) const
protectedvirtual

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

Those methods may be reimplemented to customize filtering.

Parameters
mimethe mime type to filter
filtersthe list of mime types to filter

Definition at line 2310 of file kdirlister.cpp.

bool KDirLister::doNameFilter ( const TQString &  name,
const TQPtrList< TQRegExp > &  filters 
) const
protectedvirtual

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

Those methods may be reimplemented to customize filtering.

Parameters
namethe name to filter
filtersa list of regular expressions for filtering

Definition at line 2301 of file kdirlister.cpp.

void KDirLister::emitChanges ( )
virtual

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

Definition at line 2067 of file kdirlister.cpp.

KFileItem * KDirLister::findByName ( const TQString &  name) const
virtual

Find an item by its name.

Parameters
namethe item name
Returns
the pointer to the KFileItem

Definition at line 2181 of file kdirlister.cpp.

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

Find an item by its URL.

Parameters
_urlthe item URL
Returns
the pointer to the KFileItem

Definition at line 2176 of file kdirlister.cpp.

void KDirLister::handleError ( TDEIO::Job *  job)
protectedvirtual

Reimplement to customize error handling.

Definition at line 2346 of file kdirlister.cpp.

void KDirLister::infoMessage ( const TQString &  msg)
signal

Emitted to display information about running jobs.

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

Parameters
msgthe 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 2166 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
whichspecifies 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 2689 of file kdirlister.cpp.

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

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

Parameters
itemsthe 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
dirspecifies 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().
whichspecifies 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 2694 of file kdirlister.cpp.

TQWidget * 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 2684 of file kdirlister.cpp.

bool KDirLister::matchesFilter ( const TQString &  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 2263 of file kdirlister.cpp.

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

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

bool KDirLister::matchesMimeFilter ( const TQString &  mime) const

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

Parameters
mimethe 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 2268 of file kdirlister.cpp.

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

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

const TQStringList & 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 2258 of file kdirlister.cpp.

const TQString & KDirLister::nameFilter ( ) const

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

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

Definition at line 2217 of file kdirlister.cpp.

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

Signal new items.

Parameters
itemsa 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
_urlthe directory URL.
_keepif 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.
_reloadindicates 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. unable to communicate with tdeio slave)

Definition at line 1937 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
percentthe progress in percent
void KDirLister::processedSize ( TDEIO::filesize_t  size)
signal

Regularly emitted to show the progress of this KDirLister.

Parameters
sizethe 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
_urlthe new URL
void KDirLister::redirection ( const KURL &  oldUrl,
const KURL &  newUrl 
)
signal

Signal a redirection.

Parameters
oldUrlthe original URL
newUrlthe 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
itemsthe items to refresh
KFileItem * KDirLister::rootItem ( ) const

Returns the file item of the URL.

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

Definition at line 2171 of file kdirlister.cpp.

void KDirLister::setAutoErrorHandlingEnabled ( bool  enable,
TQWidget *  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
enabletrue to enable auto error handling, false to disable
parentthe parent widget for the error dialogs, can be 0 for top-level
See also
autoErrorHandlingEnabled()

Definition at line 2051 of file kdirlister.cpp.

void KDirLister::setAutoUpdate ( bool  enable)
virtual

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

Parameters
enabletrue to enable, false to disable

Definition at line 2009 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
dirsOnlytrue to list only directories

Definition at line 2037 of file kdirlister.cpp.

void KDirLister::setMainWindow ( TQWidget *  window)

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

Parameters
windowthe window to associate with, 0 to disassociate
Since
3.1

Definition at line 2679 of file kdirlister.cpp.

void KDirLister::setMimeExcludeFilter ( const TQStringList &  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
mimeLista list of mime-types.
See also
clearMimeFilter
matchesMimeFilter
Since
3.1

Definition at line 2236 of file kdirlister.cpp.

void KDirLister::setMimeFilter ( const TQStringList &  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
mimeLista list of mime-types.
See also
clearMimeFilter
matchesMimeFilter

Definition at line 2222 of file kdirlister.cpp.

void KDirLister::setNameFilter ( const TQString &  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
filterthe new filter, TQString::null to disable filtering
See also
matchesFilter

Definition at line 2196 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
_showDotFilestrue to enable showing hidden files, false to disable
See also
showingDotFiles()

Definition at line 2023 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()

Definition at line 2018 of file kdirlister.cpp.

void KDirLister::speed ( int  bytes_per_second)
signal

Emitted to display information about the speed of the jobs.

Parameters
bytes_per_secondthe 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
_urlthe 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 1990 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
_urlthe directory URL

Definition at line 1997 of file kdirlister.cpp.

void KDirLister::totalSize ( TDEIO::filesize_t  size)
signal

Emitted when we know the size of the jobs.

Parameters
sizethe 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
_dirthe directory URL

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

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

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


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

tdeio/tdeio

Skip menu "tdeio/tdeio"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

tdeio/tdeio

Skip menu "tdeio/tdeio"
  • arts
  • dcop
  • dnssd
  • interfaces
  •   kspeech
  •     interface
  •     library
  •   tdetexteditor
  • kate
  • kded
  • kdoctools
  • kimgio
  • kjs
  • libtdemid
  • libtdescreensaver
  •     tdecore
  • tdeabc
  • tdecmshell
  • tdecore
  • tdefx
  • tdehtml
  • tdeinit
  • tdeio
  •   bookmarks
  •   httpfilter
  •   kpasswdserver
  •   kssl
  • tdeioslave
  •   http
  •   tdefile
  •   tdeio
  •   tdeioexec
  • tdemdi
  •   tdemdi
  • tdenewstuff
  • tdeparts
  • tdeprint
  • tderandr
  • tderesources
  • tdespell2
  • tdesu
  • tdeui
  • tdeunittest
  • tdeutils
  • tdewallet
Generated for tdeio/tdeio by doxygen 1.8.8
This website is maintained by Timothy Pearson.