# class KDirLister

###

Module | kio
Namespace |
Class | KDirLister
Inherits | QObject

### enums

- Changes { NONE, NAME_FILTER, MIME_FILTER, DOT_FILES, DIR_ONLY_MODE }
- OpenUrlFlag { NoFlags, Keep, Reload }
  typesafe object: OpenUrlFlags
- WhichItems { AllItems, FilteredItems }

enum details

### methods

- KDirLister (parent)

  returns ctor

  Argument | Type | Default
  --- | --- | ---
  parent | QObject | 0

  Create a directory lister.

- autoErrorHandlingEnabled ( )

  returns bool

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

- autoUpdate ( )

  returns bool

  Checks whether KDirWatch will automatically update directories. This is enabled by default. Returns true if KDirWatch is used to automatically update directories.

- canceled ( )

  returns Nothing
  SIGNAL ("canceled ()")

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

- canceled (_url)

  returns Nothing
  SIGNAL ("canceled (const KUrl&)")

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

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

  _url - the directory URL

- clear ( )

  returns Nothing
  SIGNAL ("clear ()")

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

- clear (_url)

  returns Nothing
  SIGNAL ("clear (const KUrl&)")

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

  Signal to empty the directory _url. It is only emitted if the lister is holding more than one directory.

  _url - the directory that will be emptied

- clearMimeFilter ( )

  returns Nothing

  Clears the mime based filter.

  See also setMimeFilter

- completed ( )

  returns Nothing
  SIGNAL ("completed ()")

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

- completed (_url)

  returns Nothing
  SIGNAL ("completed (const KUrl&)")

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

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

  _url - the directory URL

- delayedMimeTypes ( )

  returns bool

  Returns true if the "delayed mimetypes" feature was enabled

  See also setDelayedMimeTypes

- deleteItem (_fileItem)

  returns Nothing
  SIGNAL ("deleteItem (const KFileItem&)")

  Argument | Type | Default
  --- | --- | ---
  _fileItem | KFileItem |

  Signal an item to remove.

  _fileItem - the fileItem to delete

- dirOnlyMode ( )

  returns bool

  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

- directories ( )

  returns KUrl.List

  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

- doMimeFilter (mime, filters)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  mime | QString |
  filters | QStringList |

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

  mime - the mime type to filter

  filters - the list of mime types to filter

- doNameFilter (name, filters)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  filters | QList<QRegExp> |

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

  name - the name to filter

  filters - a list of regular expressions for filtering

- emitChanges ( )

  returns Nothing

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

- findByName (name)

  returns KFileItem

  Argument | Type | Default
  --- | --- | ---
  name | QString |

  Find an item by its name.

  name - the item name Returns the KFileItem

- findByUrl (_url)

  returns KFileItem

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

  Find an item by its URL.

  _url - the item URL Returns the KFileItem

- handleError (a0)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  a0 | KIO.Job |

  Reimplement to customize error handling

- infoMessage (msg)

  returns Nothing
  SIGNAL ("infoMessage (const QString&)")

  Argument | Type | Default
  --- | --- | ---
  msg | QString |

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

  msg - the info message

- isFinished ( )

  returns bool

  Returns true if no io operation is currently in progress. Returns true if finished, false otherwise

- items (which)

  returns KFileItemList

  Argument | Type | Default
  --- | --- | ---
  which | KDirLister.WhichItems | 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.

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

- itemsFilteredByMime (items)

  returns Nothing
  SIGNAL ("itemsFilteredByMime (const KFileItemList&)")

  Argument | Type | Default
  --- | --- | ---
  items | KFileItemList |

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

  items - the list of filtered items

- itemsForDir (dir, which)

  returns KFileItemList

  Argument | Type | Default
  --- | --- | ---
  dir | KUrl |
  which | KDirLister.WhichItems | 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.

  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.

- mainWindow ( )

  returns QWidget

  Returns the main window associated with this object. Returns the associated main window, or 0 if there is none

- matchesFilter (name)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  name | QString |

  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

- matchesFilter (a0)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  a0 | KFileItem |

  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

- matchesMimeFilter (mime)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  mime | QString |

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

  mime - the mimetype to find in the filter list. Returns true if name matches a filter in the list, otherwise false.

  See also setMimeFilter.

- matchesMimeFilter (a0)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  a0 | KFileItem |

  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

  See also setMimeFilter

- mimeFilters ( )

  returns QStringList

  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.

- nameFilter ( )

  returns QString

  Returns the current name filter, as set via setNameFilter() Returns the current name filter, can be QString() if filtering is turned off

- newItems (items)

  returns Nothing
  SIGNAL ("newItems (const KFileItemList&)")

  Argument | Type | Default
  --- | --- | ---
  items | KFileItemList |

  Signal new items.

  So use this signal only if you want to modify original KFileItems

  items - a list of new items

- openUrl (_url, _flags)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |
  _flags | KDirLister.OpenUrlFlags | 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 _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).

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

- percent (percent)

  returns Nothing
  SIGNAL ("percent (int)")

  Argument | Type | Default
  --- | --- | ---
  percent | int |

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

  percent - the progress in percent

- processedSize (size)

  returns Nothing
  SIGNAL ("processedSize (filesize_t)")

  Argument | Type | Default
  --- | --- | ---
  size | KIO.filesize_t |

  Regularly emitted to show the progress of this KDirLister.

  size - the processed size in bytes

- redirection (_url)

  returns Nothing
  SIGNAL ("redirection (const KUrl&)")

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

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

  _url - the new URL

- redirection (oldUrl, newUrl)

  returns Nothing
  SIGNAL ("redirection (const KUrl&, const KUrl&)")

  Argument | Type | Default
  --- | --- | ---
  oldUrl | KUrl |
  newUrl | KUrl |

  Signal a redirection.

  oldUrl - the original URL

  newUrl - the new URL

- refreshItems (items)

  returns Nothing
  SIGNAL ("refreshItems (const QList<QPair<KFileItem,KFileItem>>&)")

  Argument | Type | Default
  --- | --- | ---
  items | QList<QPair<KFileItem,KFileItem>> |

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

  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.

- rootItem ( )

  returns KFileItem

  Returns the file item of the URL.

  Can return an empty KFileItem. Returns the file item for url() itself (".")

- setAutoErrorHandlingEnabled (enable, parent)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  enable | bool |
  parent | QWidget |

  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.

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

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  enable | bool |

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

  enable - true to enable, false to disable

- setDelayedMimeTypes (delayedMimeTypes)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  delayedMimeTypes | bool |

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

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  dirsOnly | bool |

  Call this to list only directories. By default this option is disabled (all files will be shown).

  dirsOnly - true to list only directories

- setMainWindow (window)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  window | QWidget |

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

  window - the window to associate with, 0 to disassociate

- setMimeExcludeFilter (mimeList)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  mimeList | 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 directory. Also calling this function will not affect any named filter already set.

  mimeList - a list of mime-types.

  See also clearMimeFilter

  See also matchesMimeFilter Internal

- setMimeFilter (mimeList)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  mimeList | QStringList |

  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.

  mimeList - a list of mime-types.

  See also clearMimeFilter

  See also matchesMimeFilter

- setNameFilter (filter)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  filter | QString |

  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.

  filter - the new filter, QString() to disable filtering

  See also matchesFilter

- setShowingDotFiles (_showDotFiles)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  _showDotFiles | bool |

  Changes the "is viewing dot files" setting. Calls updateDirectory() if setting changed. By default this option is disabled (hidden files will not be shown).

  _showDotFiles - true to enable showing hidden files, false to disable

  See also showingDotFiles()

- showingDotFiles ( )

  returns bool

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

- speed (bytes_per_second)

  returns Nothing
  SIGNAL ("speed (int)")

  Argument | Type | Default
  --- | --- | ---
  bytes_per_second | int |

  Emitted to display information about the speed of the jobs.

  bytes_per_second - the speed in bytes/s

- started (_url)

  returns Nothing
  SIGNAL ("started (const KUrl&)")

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

  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.

  _url - the URL to list

- stop ( )

  returns Nothing

  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.

- stop (_url)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  _url | KUrl |

  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.

  _url - the directory URL

- totalSize (size)

  returns Nothing
  SIGNAL ("totalSize (filesize_t)")

  Argument | Type | Default
  --- | --- | ---
  size | KIO.filesize_t |

  Emitted when we know the size of the jobs.

  size - the total size in bytes

- updateDirectory (_dir)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  _dir | KUrl |

  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.

  _dir - the directory URL

- url ( )

  returns KUrl

  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.

### enums - detail

- Changes { NONE, NAME_FILTER, MIME_FILTER, DOT_FILES, DIR_ONLY_MODE }

  | NONE | - 0 | - |
  | NAME_FILTER | - 1 | - |
  | MIME_FILTER | - 2 | - |
  | DOT_FILES | - 4 | - |
  | DIR_ONLY_MODE | - 8 | - |

- OpenUrlFlag { NoFlags, Keep, Reload }

  typesafe object: OpenUrlFlags

NoFlags - 0x0 -
Keep - 0x1 -
Reload - 0x2 -

- WhichItems { AllItems, FilteredItems }

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

  | AllItems | - 0 | - |
  | FilteredItems | - 1 | - |