org.kde.koala

Class KDirLister

public class KDirLister extends QObject

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) See KDirListerSignals for signals emitted by KDirLister

    Author: Michael Brade

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

    Field Summary
    static intAllItems
    Used by items() and itemsForDir() to specify whether you want all items for a directory or just the filtered ones.
    static intDIR_ONLY_MODE
    static intDOT_FILES
    static intFilteredItems
    static intMIME_FILTER
    static intNAME_FILTER
    static intNONE
    Constructor Summary
    protected KDirLister(Class dummy)
    KDirLister(boolean _delayedMimeTypes)
    Create a directory lister.
    KDirLister()
    Method Summary
    booleanautoErrorHandlingEnabled()
    Check whether auto error handling is enabled.
    booleanautoUpdate()
    Checks whether KDirWatch will automatically update directories.
    StringclassName()
    voidclearMimeFilter()
    Clears the mime based filter.
    ArrayListdirectories()
    Returns all URLs that are listed by this KDirLister.
    booleandirOnlyMode()
    Checks whether the KDirLister only lists directories or all files.
    voiddispose()
    Delete the wrapped C++ instance ahead of finalize()
    protected booleandoMimeExcludeFilter(String mimeExclude, String[] filters)
    protected booleandoMimeFilter(String mime, String[] filters)
    Called by the public matchesMimeFilter() to do the actual filtering.
    voidemitChanges()
    Actually emit the changes made with setShowingDotFiles, setDirOnlyMode, setNameFilter and setMimeFilter.
    protected voidfinalize()
    Deletes the wrapped C++ instance
    KFileItemfind(KURL _url)
    KFileItemfindByName(String name)
    Find an item by its name.
    KFileItemfindByURL(KURL _url)
    Find an item by its URL.
    protected voidhandleError(Job arg1)
    Reimplement to customize error handling @short Reimplement to customize error handling
    booleanisDisposed()
    Has the wrapped C++ instance been deleted?
    booleanisFinished()
    Returns true if no io operation is currently in progress.
    ArrayListitems(int which)
    Returns the items listed for the current url().
    ArrayListitems()
    ArrayListitemsForDir(KURL dir, int which)
    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.
    ArrayListitemsForDir(KURL dir)
    QWidgetmainWindow()
    Returns the main window associated with this object.
    booleanmatchesFilter(String name)
    Checks whether name matches a filter in the list of name filters.
    protected booleanmatchesFilter(KFileItem arg1)
    Called for every new item before emitting newItems().
    booleanmatchesMimeFilter(String mime)
    Checks whether mime matches a filter in the list of mime types
    protected booleanmatchesMimeFilter(KFileItem arg1)
    Called for every new item before emitting newItems().
    QMetaObjectmetaObject()
    ArrayListmimeFilters()
    Returns the list of mime based filters, as set via setMimeFilter().
    StringnameFilter()
    Returns the current name filter, as set via setNameFilter()
    booleanopenURL(KURL _url, boolean _keep, boolean _reload)
    Run the directory lister on the given url.
    booleanopenURL(KURL _url, boolean _keep)
    booleanopenURL(KURL _url)
    KFileItemrootItem()
    Returns the file item of the URL.
    voidsetAutoErrorHandlingEnabled(boolean enable, QWidget parent)
    Enable or disable auto error handling is enabled.
    voidsetAutoUpdate(boolean enable)
    Enable/disable automatic directory updating, when a directory changes (using KDirWatch).
    voidsetDirOnlyMode(boolean dirsOnly)
    Call this to list only directories.
    voidsetMainWindow(QWidget window)
    Pass the main window this object is associated with this is used for caching authentication data
    voidsetMimeExcludeFilter(String[] mimeList)
    Filtering should be done with KFileFilter.
    voidsetMimeFilter(String[] mimeList)
    Set mime-based filter to only list items matching the given mimetypes.
    voidsetNameFilter(String filter)
    Set a name filter to only list items matching this name, e.g.
    voidsetShowingDotFiles(boolean _showDotFiles)
    Changes the "is viewing dot files" setting.
    booleanshowingDotFiles()
    Checks whether hidden files (files beginning with a dot) will be shown.
    voidstop()
    Stop listing all directories currently being listed.
    voidstop(KURL _url)
    Stop listing the given directory.
    voidupdateDirectory(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.
    KURLurl()
    Returns the top level URL that is listed by this KDirLister.
    protected booleanvalidURL(KURL arg1)
    Checks if an url is malformed or not and displays an error message if it is and autoErrorHandling is set to true.

    Field Detail

    AllItems

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

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

    DIR_ONLY_MODE

    public static final int DIR_ONLY_MODE

    DOT_FILES

    public static final int DOT_FILES

    FilteredItems

    public static final int FilteredItems

    MIME_FILTER

    public static final int MIME_FILTER

    NAME_FILTER

    public static final int NAME_FILTER

    NONE

    public static final int NONE

    Constructor Detail

    KDirLister

    protected KDirLister(Class dummy)

    KDirLister

    public KDirLister(boolean _delayedMimeTypes)
    Create a directory lister.

    Parameters: _delayedMimeTypes if true, mime types will be fetched on demand. If false, they will always be fetched immediately

    UNKNOWN: Create a directory lister.

    KDirLister

    public KDirLister()

    Method Detail

    autoErrorHandlingEnabled

    public boolean autoErrorHandlingEnabled()
    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: KDirLister

    UNKNOWN: Check whether auto error handling is enabled.

    autoUpdate

    public boolean autoUpdate()
    Checks whether KDirWatch will automatically update directories. This is enabled by default.

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

    UNKNOWN: Checks whether KDirWatch will automatically update directories.

    className

    public String className()

    clearMimeFilter

    public void clearMimeFilter()
    Clears the mime based filter.

    See Also: KDirLister

    UNKNOWN: Clears the mime based filter.

    directories

    public ArrayList directories()
    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

    UNKNOWN: Returns all URLs that are listed by this KDirLister.

    dirOnlyMode

    public boolean dirOnlyMode()
    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

    UNKNOWN: Checks whether the KDirLister only lists directories or all files.

    dispose

    public void dispose()
    Delete the wrapped C++ instance ahead of finalize()

    doMimeExcludeFilter

    protected boolean doMimeExcludeFilter(String mimeExclude, String[] filters)

    UNKNOWN:

    doMimeFilter

    protected boolean doMimeFilter(String mime, String[] 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

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

    emitChanges

    public void emitChanges()
    Actually emit the changes made with setShowingDotFiles, setDirOnlyMode, setNameFilter and setMimeFilter.

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

    finalize

    protected void finalize()
    Deletes the wrapped C++ instance

    find

    public KFileItem find(KURL _url)

    findByName

    public KFileItem findByName(String name)
    Find an item by its name.

    Parameters: name the item name

    Returns: the pointer to the KFileItem

    UNKNOWN: Find an item by its name.

    findByURL

    public KFileItem findByURL(KURL _url)
    Find an item by its URL.

    Parameters: _url the item URL

    Returns: the pointer to the KFileItem

    UNKNOWN: Find an item by its URL.

    handleError

    protected void handleError(Job arg1)
    Reimplement to customize error handling @short Reimplement to customize error handling

    isDisposed

    public boolean isDisposed()
    Has the wrapped C++ instance been deleted?

    isFinished

    public boolean isFinished()
    Returns true if no io operation is currently in progress.

    Returns: true if finished, false otherwise

    UNKNOWN: Returns true if no io operation is currently in progress.

    items

    public ArrayList items(int which)
    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().

    UNKNOWN: Returns the items listed for the current url().

    items

    public ArrayList items()

    itemsForDir

    public ArrayList itemsForDir(KURL dir, int which)
    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 boolean 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.

    UNKNOWN: Returns the items listed for the given dir.

    itemsForDir

    public ArrayList itemsForDir(KURL dir)

    mainWindow

    public QWidget mainWindow()
    Returns the main window associated with this object.

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

    UNKNOWN: Returns the main window associated with this object.

    matchesFilter

    public boolean matchesFilter(String name)
    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: KDirLister

    UNKNOWN: Checks whether name matches a filter in the list of name filters.

    matchesFilter

    protected boolean matchesFilter(KFileItem arg1)
    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: KDirLister KDirLister

    UNKNOWN: Called for every new item before emitting newItems().

    matchesMimeFilter

    public boolean matchesMimeFilter(String mime)
    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: #

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

    matchesMimeFilter

    protected boolean matchesMimeFilter(KFileItem arg1)
    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: KDirLister KDirLister

    UNKNOWN: Called for every new item before emitting newItems().

    metaObject

    public QMetaObject metaObject()

    mimeFilters

    public ArrayList mimeFilters()
    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.

    UNKNOWN: Returns the list of mime based filters, as set via setMimeFilter().

    nameFilter

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

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

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

    openURL

    public boolean openURL(KURL _url, boolean _keep, boolean _reload)
    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(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. _keep if 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. _reload indicates 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. invalid _url)

    UNKNOWN: Run the directory lister on the given url.

    openURL

    public boolean openURL(KURL _url, boolean _keep)

    openURL

    public boolean openURL(KURL _url)

    rootItem

    public KFileItem rootItem()
    Returns the file item of the URL.

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

    UNKNOWN: Returns the file item of the URL.

    setAutoErrorHandlingEnabled

    public void setAutoErrorHandlingEnabled(boolean 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: KDirLister

    UNKNOWN: Enable or disable auto error handling is enabled.

    setAutoUpdate

    public void setAutoUpdate(boolean enable)
    Enable/disable automatic directory updating, when a directory changes (using KDirWatch).

    Parameters: enable true to enable, false to disable

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

    setDirOnlyMode

    public void setDirOnlyMode(boolean dirsOnly)
    Call this to list only directories. By default this option is disabled (all files will be shown).

    Parameters: dirsOnly true to list only directories

    UNKNOWN: Call this to list only directories.

    setMainWindow

    public void 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

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

    setMimeExcludeFilter

    public void setMimeExcludeFilter(String[] 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: mimeList a list of mime-types.

    See Also: KDirLister KDirLister

    UNKNOWN: Filtering should be done with KFileFilter.

    setMimeFilter

    public void setMimeFilter(String[] mimeList)
    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: mimeList a list of mime-types.

    See Also: KDirLister KDirLister

    UNKNOWN: Set mime-based filter to only list items matching the given mimetypes.

    setNameFilter

    public void setNameFilter(String 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 direcory is not automatically reloaded.

    Parameters: filter the new filter, null to disable filtering

    See Also: KDirLister

    UNKNOWN: Set a name filter to only list items matching this name, e.

    setShowingDotFiles

    public void setShowingDotFiles(boolean _showDotFiles)
    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: _showDotFiles true to enable showing hidden files, false to disable

    See Also: KDirLister

    UNKNOWN: Changes the "is viewing dot files" setting.

    showingDotFiles

    public boolean showingDotFiles()
    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: KDirLister

    UNKNOWN: Checks whether hidden files (files beginning with a dot) will be shown.

    stop

    public void stop()
    Stop listing all directories currently being listed. Emits canceled() if there was at least one job running. Emits canceled( KURL ) for each stopped job if there are at least two dirctories being watched by KDirLister.

    UNKNOWN: Stop listing all directories currently being listed.

    stop

    public void stop(KURL _url)
    Stop listing the given directory. Emits canceled() if the killed job was the last running one. Emits canceled( 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

    UNKNOWN: Stop listing the given directory.

    updateDirectory

    public void updateDirectory(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

    UNKNOWN: Update the directory _dir.

    url

    public KURL url()
    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.

    UNKNOWN: Returns the top level URL that is listed by this KDirLister.

    validURL

    protected boolean validURL(KURL arg1)
    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.

    UNKNOWN: Checks if an url is malformed or not and displays an error message if it is and autoErrorHandling is set to true.