class KDirLister

# class KDirLister | Helper class for the kiojob used to list and update a directory. More...
Definition | `#include <kdirlister.h>`
Inherits | QObject (qt) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Signals

- void started ( const KURL& _url )
- void completed ()
- void completed ( const KURL& _url )
- void canceled ()
- void canceled ( const KURL& _url )
- void redirection ( const KURL& _url )
- void redirection ( const KURL& oldUrl, const KURL& newUrl )
- void clear ()
- void clear ( const KURL& _url )
- void newItems ( const KFileItemList& items )
- void itemsFilteredByMime ( const KFileItemList& items )
- void deleteItem ( KFileItem *_fileItem )
- void refreshItems ( const KFileItemList& items )
- void infoMessage ( const QString& msg )
- void percent ( int percent )
- void totalSize ( KIO::filesize_t size )
- void processedSize ( KIO::filesize_t size )
- void speed ( int bytes_per_second )

#### Protected Types

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

#### Protected Methods

- virtual bool matchesFilter ( const KFileItem * ) const
- virtual bool matchesMimeFilter ( const KFileItem * ) const
- virtual bool doNameFilter ( const QString& name, const QPtrList<QRegExp>& filters ) const
- virtual bool doMimeFilter ( const QString& mime, const QStringList& filters ) const
- bool doMimeExcludeFilter ( const QString& mimeExclude, const QStringList& filters ) const
- virtual bool validURL ( const KURL& ) const
- virtual void handleError ( KIO::Job* )
- virtual void virtual_hook ( int id, void* data )

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

void started ( const KURL& _url ) | ### started

[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 completed () | ### completed

[signal]

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

void completed ( const KURL& _url ) | ### completed

[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 canceled () | ### canceled

[signal]

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

void canceled ( const KURL& _url ) | ### canceled

[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 redirection ( const KURL& _url ) | ### redirection

[signal]

Signal a redirection. Only emitted if there's just one directory to list, i.e. most probably openURL() has been called with @p_keep == false.

Parameters:

_url | the new URL

void redirection ( const KURL& oldUrl, const KURL& newUrl ) | ### redirection

[signal]

Signal a redirection.

Parameters:

oldUrl | the original URL
newUrl | the new URL

void clear () | ### clear

[signal]

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

void clear ( const KURL& _url ) | ### clear

[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 newItems ( const KFileItemList& items ) | ### newItems

[signal]

Signal new items.

Parameters:

items | a list of new items

void itemsFilteredByMime ( const KFileItemList& items ) | ### itemsFilteredByMime

[signal]

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

Parameters:

items | the list of filtered items

void deleteItem ( KFileItem *_fileItem ) | ### deleteItem

[signal]

Signal an item to remove.

ATTENTION: if `_fileItem` == rootItem() the directory this lister is holding was deleted and you HAVE to release especially the rootItem() of this lister, otherwise your app will CRASH!! The clear() signals have been emitted already.

Parameters:

the | fileItem to delete

void refreshItems ( const KFileItemList& items ) | ### refreshItems

[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

void infoMessage ( const QString& msg ) | ### infoMessage

[signal]

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

Parameters:

msg | the info message

void percent ( int percent ) | ### percent

[signal]

Progress signal showing the overall progress of the KDirLister. This allows using a progress bar very easily. (see KProgress)

Parameters:

percent | the progress in percent

void totalSize ( KIO::filesize_t size ) | ### totalSize

[signal]

Emitted when we know the size of the jobs.

Parameters:

size | the total size in bytes

void processedSize ( KIO::filesize_t size ) | ### processedSize

[signal]

Regularly emitted to show the progress of this KDirLister.

Parameters:

size | the processed size in bytes

void speed ( int bytes_per_second ) | ### speed

[signal]

Emitted to display information about the speed of the jobs.

Parameters:

bytes_per_second | the speed in bytes/s

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

[protected]

bool matchesFilter ( const KFileItem * ) | ### matchesFilter

[protected const virtual]

Called for every new item before emitting newItems(). You may reimplement this method in a subclass to implement your own filtering. The default implementation filters out ".." and everything not matching the name filter(s)

Returns: true if the item is "ok". false if the item shall not be shown in a view, e.g. files not matching a pattern *.cpp (KFileItem::isHidden())

See also: matchesFilter, setNameFilter

bool matchesMimeFilter ( const KFileItem * ) | ### matchesMimeFilter

[protected const virtual]

Called for every new item before emitting newItems(). You may reimplement this method in a subclass to implement your own filtering. The default implementation filters out ".." and everything not matching the name filter(s)

Returns: true if the item is "ok". false if the item shall not be shown in a view, e.g. files not matching a pattern *.cpp (KFileItem::isHidden())

See also: matchesMimeFilter, setMimeFilter

bool doNameFilter ( const QString& name, const QPtrList<QRegExp>& filters ) | ### doNameFilter

[protected const virtual]

Called by the public matchesFilter() to do the actual filtering. Those methods may be reimplemented to customize filtering.

Parameters:

name | the name to filter
filers | a list of regular expressions for filtering

bool doMimeFilter ( const QString& mime, const QStringList& filters ) | ### doMimeFilter

[protected const 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

bool doMimeExcludeFilter ( const QString& mimeExclude, const QStringList& filters ) | ### doMimeExcludeFilter

[protected const]

bool validURL ( const KURL& ) | ### validURL

[protected const 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.

void handleError ( KIO::Job* ) | ### handleError

[protected virtual]

void virtual_hook ( int id, void* data ) | ### virtual_hook

[protected virtual]

Generated by: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:57 2003, using kdoc 2.0a54.