Source: kdiroperator.h


Annotated List
Files
Globals
Hierarchy
Index
// -*- c++ -*-
/* This file is part of the KDE libraries
    Copyright (C) 1999 Stephan Kulow 
		  2000,2001 Carsten Pfeiffer 

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*/
#ifndef KDIROPERATOR_H_
#define KDIROPERATOR_H_

#include 
#include 

#include 
#include 

#include 
#include 
#include 

class QPopupMenu;
class QTimer;

class KAction;
class KToggleAction;
class KActionSeparator;
class KActionMenu;
class KFileReader;
class QWidgetStack;
class KProgress;
namespace KIO {
  class DeleteJob;
}

/**
 * This widget works as a network transparent filebrowser. You specify a URL
 * to display and this url will be loaded via @ref KDirLister. The user can
 * browse through directories, highlight and select files, delete or rename
 * files.
 *
 * It supports different views, e.g. a detailed view (see @KFileDetailView),
 * a simple icon view (see @KFileIconView), a combination of two views,
 * separating directories and files (@see KCombiView).
 *
 * Additionally, a preview view is available (see @KFilePreview), which can
 * show either a simple or detailed view and additionally a preview widget
 * (see @ref setPreviewWidget()). @ref KImageFilePreview is one implementation
 * of a preview widget, that displays previews for all supported filetypes
 * utilizing KIO::PreviewJob.
 *
 * Currently, those classes don't support Drag&Drop out of the box -- there
 * you have to use your own view-classes. You can use some DnD-aware views
 * from Björn Sahlström  until they will be integrated
 * into this library. See http://master.kde.org/~pfeiffer/DnD-classes.tar.gz
 *
 * This widget is the one used in the KFileDialog.
 *
 * Basic usage is like this:
 * 
 *   KDirOperator *op = new KDirOperator( KURL( "file:/home/gis" ), this );
 *   // some signals you might be interested in
 *   connect(op, SIGNAL(updateInformation(int, int)),
 *           SLOT(updateStatusLine(int, int)));
 *   connect(op, SIGNAL(urlEntered(const KURL&)),
 *           SLOT(urlEntered(const KURL&)));
 *   connect(op, SIGNAL(fileHighlighted(const KFileViewItem *)),
 *           SLOT(fileHighlighted(const KFileViewItem *)));
 *   connect(op, SIGNAL(fileSelected(const KFileViewItem *)),
 *           SLOT(fileSelected(const KFileViewItem *)));
 *   connect(op, SIGNAL(finishedLoading()),
 *           SLOT(slotLoadingFinished()));
 *
 *   op->readConfig( KGlobal::config(), "Your KDiroperator ConfigGroup" );
 *   op->setView(KFile::Default);
 * 
* * This will create a childwidget of 'this' showing the directory contents * of /home/gis in the default-view. The view is determined by the readConfig() * call, which will read the KDirOperator settings, the user left your program * with (and which you saved with op->saveConfig()). * * @short A widget for displaying files and browsing directories. * @author Stephan Kulow , Carsten Pfeiffer */ class KDirOperator : public QWidget { Q_OBJECT public: /** * Constructs the KDirOperator with no initial view. As the views are * configurable, call @ref readConfig() to load the user's configuration * and then @ref setView to explicitly set a view. * * This constructor doesn't start loading the url, @ref setView will do it. */ KDirOperator(const KURL& urlName = KURL(), QWidget *parent = 0, const char* name = 0); /** * Destroys the KDirOperator. */ virtual ~KDirOperator(); /** * Enable/disable showing hidden files. */ void setShowHiddenFiles ( bool s ) { showHiddenAction->setChecked( s ); } /** * @returns true when hidden files are shown or false otherwise. */ bool showHiddenFiles () const { return showHiddenAction->isChecked(); } /** * Stops loading immediately. You don't need to call this, usually. */ void close(); /** * Set a filter like "*.cpp *.h *.o". Only files matching that filter * will be shown. Call @ref rereadDir() to apply it. * * @see KDirLister::setNameFilter * @see #nameFilter */ void setNameFilter(const QString& filter); /** * @returns the current namefilter. * @see #setNameFilter */ const QString& nameFilter() const { return dir->nameFilter(); } /** * Sets a list of mimetypes as filter. Only files of those mimetypes * will be shown. * * Example: *
     * QStringList filter;
     * filter << "text/html" << "image/png" << "inode/directory";
     * dirOperator->setMimefilter( filter );
     * 
* * Node: Without the mimetype inode/directory, only files would be shown. * * @see KDirLister::setMimeFilter * @see #mimeFilter */ void setMimeFilter( const QStringList& mimetypes ); QStringList mimeFilter() const { return dir->mimeFilters(); } /** * Clears both the namefilter and mimetype filter, so that all files and * directories will be shown. * * @see #setMimeFilter * @see #setNameFilter */ void clearFilter(); /** * @returns the current url */ KURL url() const; /** * Sets a new url to list. * @param clearforward specifies whether the "forward" history should be * cleared. */ void setURL(const KURL& url, bool clearforward); /** * Clears the current selection and attempts to set @p filename * the current file. filename is just the name, no path or url. */ void setCurrentItem( const QString& filename ); /** * Sets a new KFileView to be used for showing and browsing files. * Note: this will read the current @ref url() to fill the view. * * @see KFileView * @see KFileIconView * @see KFileDetailView * @see KFileCombiView * @see #view */ void setView(KFileView *view); /** * @returns the currently used view. * @see #setView */ // ### make non-const const KFileView * view() const { return fileView; } /** * Returns the widget of the current view. 0L if there is no view/widget. * (KFileView itself is not a widget.) */ QWidget * viewWidget() const { return fileView ? fileView->widget() : 0L; } /** * Sets one of the predefine fileviews * @see KFile::FileView */ void setView(KFile::FileView view); /** * Sets the way to sort files and directories. */ void setSorting( QDir::SortSpec ); /** * @returns the current way of sorting files and directories */ QDir::SortSpec sorting() const { return mySorting; } /** * @returns true if we are displaying the root directory of the current url */ bool isRoot() const; /** * @returns the object listing the directory (KFileReader inherits * KDirLister). */ KFileReader *fileReader() const { return dir; } /** * @returns the progress widget, that is shown during directory listing. * You can for example reparent() it to put it into a statusbar. */ KProgress * progressBar() const; /** * Sets the listing/selection mode for the views, an OR'ed combination of * @li File * @li Directory * @li Files * @li ExistingOnly * @li LocalOnly * * You cannot mix File and Files of course, as the former means * single-selection mode, the latter multi-selection. */ void setMode( KFile::Mode m ); KFile::Mode mode() const; /** * Sets a preview-widget to be shown next to the file-view. * The ownership of @p w is transferred to KDirOperator, so don't * delete it yourself! */ void setPreviewWidget(const QWidget *w); /** * @returns a list of all currently selected items. If there is no view, * then 0L is returned. */ const KFileViewItemList * selectedItems() const { return ( fileView ? fileView->selectedItems() : 0L ); } /** * @returns true if @p item is currently selected, or false otherwise. */ inline bool isSelected( const KFileViewItem *item ) const { return ( fileView ? fileView->isSelected( item ) : false ); } /** * @returns the number of directories in the currently listed url. * Returns 0 if there is no view. */ int numDirs() const; /** * @returns the number of files in the currently listed url. * Returns 0 if there is no view. */ int numFiles() const; /** * @returns a KCompletion object, containing all filenames and * directories of the current directory/URL. * You can use it to insert it into a @ref KLineEdit or @ref KComboBox * Note: it will only contain files, after @ref prepareCompletionObjects() * has been called. It will be implicitly called from @ref makeCompletion() * or @ref makeDirCompletion() */ KCompletion * completionObject() const { return const_cast( &myCompletion ); } /** * @returns a KCompletion object, containing only all directories of the * current directory/URL. * You can use it to insert it into a @ref KLineEdit or @ref KComboBox * Note: it will only contain directories, after * @ref prepareCompletionObjects() has been called. It will be implicitly * called from @ref makeCompletion() or @ref makeDirCompletion() */ KCompletion *dirCompletionObject() const { return const_cast( &myDirCompletion ); } /** * an accessor to a collection of all available Actions. The actions * are static, they will be there all the time (no need to connect to * the signals KActionCollection::inserted() or removed(). * * There are the following actions: * * @li popupMenu : an ActionMenu presenting a popupmenu with all actions * @li up : changes to the parent directory * @li back : goes back to the previous directory * @li forward : goes forward in the history * @li home : changes to the user's home directory * @li reload : reloads the current directory * @li separator : a separator * @li mkdir : opens a dialog box to create a directory * @li delete : deletes the selected files/directories * @li sorting menu : an ActionMenu containing all sort-options * @li by name : sorts by name * @li by date : sorts by date * @li by size : sorts by size * @li reversed : reverses the sort order * @li dirs first : sorts directories before files * @li case insensitive : sorts case insensitively * @li view menu : an ActionMenu containing all actions concerning the view * @li short view : shows a simple fileview * @li detailed view : shows a detailed fileview (dates, permissions ,...) * @li show hidden : shows hidden files * @li separate dirs : shows directories in a separate pane * @li preview : shows a preview next to the fileview * @li single : hides the separate view for directories or the preview * @li properties : shows a KPropertiesDialog for the selected files * * The short and detailed view are in an exclusive group. The sort-by * actions are in an exclusive group as well. Also the "separate dirs", * "preview" and "single" actions are in an exclusive group. * * You can e.g. use *
actionCollection()->action( "up" )->plug( someToolBar );
* to add a button into a toolbar, which makes the dirOperator change to * its parent directory. * * @returns all available Actions */ KActionCollection * actionCollection() const { return myActionCollection; } /** * Reads the default settings for a view, i.e. the default KFile::FileView. * Also reads the sorting and whether hidden files should be shown. * Note: the default view will not be set - you have to call *
@ref setView( KFile::Default )
to apply it. * * @see #saveConfig */ virtual void readConfig( KConfig *, const QString& group = QString::null ); /** * Saves the current settings like sorting, simple or detailed view. * * @see #readConfig */ virtual void saveConfig( KConfig *, const QString& group = QString::null ); /** * This is a KFileDialog specific hack: we want to select directories with * single click, but not files. But as a generic class, we have to be able * to select files on single click as well. * * This gives us the opportunity to do both. * * The default is false, set it to true if you don't want files selected * with single click. */ void setOnlyDoubleClickSelectsFiles( bool enable ); /** * @returns whether files (not directories) should only be select()ed by * double-clicks. * @see #setOnlyDoubleClickSelectsFiles */ bool onlyDoubleClickSelectsFiles() const; /** * Creates the given directory/url. If it is a relative path, * it will be completed with the current directory. * If enterDirectory is true, the directory will be entered after a * successful operation. If unsuccessful, a messagebox will be presented * to the user. * @returns true if the directory could be created. */ bool mkdir( const QString& directory, bool enterDirectory = true ); /** * Starts and returns a @ref KIO::DeleteJob to delete the given @p items. * * @param ask specifies whether a confirmation dialog should be shown * @param showProgress passed to the DeleteJob to show a progress dialog */ KIO::DeleteJob * del( const KFileViewItemList& items, bool ask = true, bool showProgress = true ); /** * Clears the forward and backward history. */ void clearHistory(); /** * When going up in the directory hierarchy, KDirOperator can highlight * the directory that was just left. * * I.e. when you go from /home/gis/src to /home/gis, the item "src" will * be made the current item. * * Default is off. */ void setEnableDirHighlighting( bool enable ); /** * @returns whether the last directory will be made the current item * when going up in the directory hierarchy. * * Default is false. */ bool dirHighlighting() const; /** * @returns true if we are in directory-only mode, that is, no files are * shown. */ bool dirOnlyMode() const { return ( (myMode & KFile::Directory) && (myMode & (KFile::File | KFile::Files)) == 0 ); } protected: /** * Sets a custom KFileReader to list directories. */ void setFileReader( KFileReader *reader ); /** * @reimplemented */ void resizeEvent( QResizeEvent * ); /** * Sets up all the actions. Called from the constructor, you usually * better not call this. */ void setupActions(); /** * Updates the sorting-related actions to comply with the current sorting * @see #sorting */ void updateSortActions(); /** * Updates the view-related actions to comply with the current * KFile::FileView */ void updateViewActions(); /** * Sets up the context-menu with all the necessary actions. Called from the * constructor, you usually don't need to call this. */ void setupMenu(); /** * Synchronizes the completion objects with the entries of the * currently listed url. * * Automatically called from @ref makeCompletion() and * @ref makeDirCompletion() */ void prepareCompletionObjects(); /** * Checks if there support from @ref KIO::PreviewJob for the currently * shown files, taking @ref mimeFilter() and @ref nameFilter() into account * Enables/disables the preview-action accordingly. */ bool checkPreviewSupport(); public slots: /** * Goes one step back in the history and opens that url. */ void back(); /** * Goes one step forward in the history and opens that url. */ void forward(); /** * Enters the home directory. */ void home(); /** * Goes one directory up from the current url. */ void cdUp(); /** * Re-reads the current url. */ void rereadDir(); /** * Opens a dialog to create a new directory. */ void mkdir(); /** * Deletes the currently selected files/directories. */ void deleteSelected(); /** * Enables/disables actions that are selection dependent. Call this e.g. * when you are about to show a popup menu using some of KDirOperators * actions. */ void updateSelectionDependentActions(); /** * Tries to complete the given string (only completes files). */ QString makeCompletion(const QString&); /** * Tries to complete the given string (only completes directores). */ QString makeDirCompletion(const QString&); protected slots: /** * Restores the normal cursor after showing the busy-cursor. Also hides * the progressbar. */ void resetCursor(); /** * @internal */ // ### make private void readNextMimeType(); /** * Called after @ref setURL() to load the directory, update the history, * etc. */ void pathChanged(); /** * @internal */ // ### remove for KDE 3 void filterChanged(); /** * Adds a new list of KFileItems to the view * (coming from KFileReader/KDirLister) */ void insertNewFiles(const KFileItemList &newone); /** * Removes the given KFileItem item from the view (usually called from * KFileReader/KDirLister). */ void itemDeleted(KFileItem *); /** * Enters the directory specified by the given @p item. */ void selectDir(const KFileViewItem *item ); /** * Emits fileSelected( item ) */ void selectFile(const KFileViewItem *item); /** * Emits fileHighlighted( i ) */ void highlightFile(const KFileViewItem* i) { emit fileHighlighted( i ); } /** * Called upon right-click to activate the popupmenu. */ virtual void activatedMenu( const KFileViewItem * ); /** * Changes sorting to sort by name */ void sortByName() { byNameAction->setChecked( true ); } /** * Changes sorting to sort by size */ void sortBySize() { bySizeAction->setChecked( true ); } /** * Changes sorting to sort by date */ void sortByDate() { byDateAction->setChecked( true ); } /** * Changes sorting to reverse sorting */ void sortReversed() { reverseAction->setChecked( !reverseAction->isChecked() ); } /** * Toggles showing directories first / having them sorted like files. */ void toggleDirsFirst() { dirsFirstAction->setChecked( !dirsFirstAction->isChecked() ); } /** * Toggles case sensitive / case insensitive sorting */ void toggleIgnoreCase() { caseInsensitiveAction->setChecked( !caseInsensitiveAction->isChecked() ); } /** * @p internal */ // ### make private void deleteOldView(); /** * Tries to make the given @p match as current item in the view and emits * completion( match ) */ void slotCompletionMatch(const QString& match); signals: void urlEntered(const KURL& ); void updateInformation(int files, int dirs); void completion(const QString&); void finishedLoading(); /** * Emitted whenever the current fileview is changed, either by an explicit * call to @ref setView() or by the user selecting a different view thru * the GUI. */ void viewChanged( KFileView * newView ); void fileHighlighted(const KFileViewItem*); void dirActivated(const KFileViewItem*); void fileSelected(const KFileViewItem*); private: /** * Contains all URLs you can reach with the back button. */ QStack backStack; /** * Contains all URLs you can reach with the forward button. */ QStack forwardStack; static KURL *lastDirectory; KFileReader *dir; KCompletion myCompletion; KCompletion myDirCompletion; bool myCompleteListDirty; QDir::SortSpec mySorting; /** * Checks whether we preview support is available for the current * mimetype/namefilter */ bool checkPreviewInternal() const; /** * takes action on the new location. If it's a directory, change * into it, if it's a file, correct the name, etc. */ void checkPath(const QString& txt, bool takeFiles = false); void connectView(KFileView *); // for the handling of the cursor bool finished; KFileView *fileView; KFileView *oldView; KFileViewItemList pendingMimeTypes; // the enum KFile::FileView as an int int viewKind; int defaultView; KFile::Mode myMode; KProgress *progress; const QWidget *myPreview; // temporary pointer for the preview widget // actions for the popupmenus // ### clean up all those -- we have them all in the actionMenu! KActionMenu *actionMenu; KAction *backAction; KAction *forwardAction; KAction *homeAction; KAction *upAction; KAction *reloadAction; KActionSeparator *actionSeparator; KAction *mkdirAction; KActionMenu *sortActionMenu; KRadioAction *byNameAction; KRadioAction *byDateAction; KRadioAction *bySizeAction; KToggleAction *reverseAction; KToggleAction *dirsFirstAction; KToggleAction *caseInsensitiveAction; KActionMenu *viewActionMenu; KRadioAction *shortAction; KRadioAction *detailedAction; KToggleAction *showHiddenAction; KToggleAction *separateDirsAction; KActionCollection *myActionCollection; private slots: void slotDetailedView(); void slotSimpleView(); void slotToggleHidden( bool ); void slotSingleView(); void slotSeparateDirs(); void slotDefaultPreview(); void slotSortByName(); void slotSortBySize(); void slotSortByDate(); void slotSortReversed(); void slotToggleDirsFirst(); void slotToggleIgnoreCase(); void slotStarted(); void slotProgress( KIO::Job *, unsigned long ); void slotShowProgress(); void slotIOFinished(); void slotRedirected( const KURL& ); void slotViewActionAdded( KAction * ); void slotViewActionRemoved( KAction * ); void slotViewSortingChanged(); void slotProperties(); private: class KDirOperatorPrivate; KDirOperatorPrivate *d; }; #endif

Generated by: dfaure on kde.faure.org on Thu Jan 17 22:17:38 2002, using kdoc 2.0a53.