// -*- c++ -*-
/* This file is part of the KDE libraries
Copyright (C) 1997, 1998 Richard Moore
1998 Stephan Kulow
1998 Daniel Grana
2000,2001 Carsten Pfeiffer
2001 Frerich Raabe
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 __KFILEDIALOG_H__
#define __KFILEDIALOG_H__
#include
#include
#include
#include
#include
#include
class QCheckBox;
class QHBoxLayout;
class QGridLayout;
class QLabel;
class QPopupMenu;
class QVBoxLayout;
class KDirOperator;
class KFileBookmark;
class KFileBookmarkManager;
class KURLComboBox;
class KFileFilter;
class KFileView;
class KFileViewItem;
class KToolBar;
class KPreviewWidgetBase;
struct KFileDialogPrivate;
/**
* Provide a user (and developer) friendly way to
* select files and directories.
*
* The widget can be used as a drop in replacement for the
* @ref QFileDialog widget, but has greater functionality and a nicer GUI.
*
* You will usually want to use one of the static methods
* @ref getOpenFileName(), @ref getSaveFileName(), @ref getOpenURL()
* or for multiple files @ref getOpenFileNames() or @ref getOpenURLs().
*
* The dialog has been designed to allow applications to customise it
* by subclassing. It uses geometry management to ensure that subclasses
* can easily add children that will be incorporated into the layout.
*
* @image kfiledialog.png KFileDialog
*
* @short A file selection dialog.
*
* @author Richard J. Moore , Carsten Pfeiffer
*/
class KFileDialog : public KDialogBase
{
Q_OBJECT
public:
/**
* Defines some default behavior of the filedialog.
* E.g. in mode @p Opening and @p Saving, the selected files/urls will
* be added to the "recent documents" list. The Saving mode also implies
* @ref setKeepLocation() being set.
*
* @p Other means that no default actions are performed.
*
* @see #setOperationMode
* @see #operationMode
*/
enum OperationMode { Other = 0, Opening, Saving };
/**
* Construct a file dialog.
*
* @param startDir This can either be
* @li The URL of the directory to start in.
* @li @ref QString::null to start in the current working
* directory, or the last directory where a file has been
* selected.
* @li ':' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::
* kfile->setFilter("*.cpp|C++ Source Files\n*.h|Header files");
* kfile->setFilter("*.cpp");
* kfile->setFilter("*.cpp|Sources (*.cpp)");
* kfile->setFilter("*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header files");
*
*
* Note: The text to display is not parsed in any way. So, if you
* want to show the suffix to select by a specific filter, you must
* repeat it.
*
* If the filter contains a '/', a mimetype-filter is assumed. You can
* specify multiple mimetypes like this (separated with space):
*
*
* kfile->setFilter( "image/png text/html text/plain" );
*
*
* @see #filterChanged
* @see #setMimeFilter
*/
void setFilter(const QString& filter);
/**
* Retrieve the current filter as entered by the user or one of the
* predefined set via @ref setFilter().
*
* @param filter Contains the new filter (only the extension part,
* not the explanation), for example, "*.cpp" or "*.cpp *.cc".
*
* @see setFilter()
* @see filterChanged()
*/
QString currentFilter() const;
/**
* Set the filter up to specify the output type.
*
* @param label the label to use instead of "Filter:"
* @param types a list of mimetypes that can be used as output format
* @param defaultType the default mimetype to use as output format.
*
* Do not use in conjunction with @ref setFilter()
* @deprecated
*/
void setFilterMimeType(const QString &label, const KMimeType::List &types, const KMimeType::Ptr &defaultType);
/**
* The mimetype for the desired output format.
*
* This is only valid if @ref setFilterMimeType() has been called
* previously.
*
* @see setFilterMimeType()
*/
KMimeType::Ptr currentFilterMimeType();
/**
* Set the filter up to specify the output type.
*
* @param types a list of mimetypes that can be used as output format
* @param defaultType the default mimetype to use as output format, if any.
* If @p defaultType is set, it will be set as the current item.
* Otherwise, a first item showing all the mimetypes will be created.
* Typically, @p defaultType should be empty for loading and set for saving.
*
* Do not use in conjunction with @ref setFilter()
*/
void setMimeFilter( const QStringList& types,
const QString& defaultType = QString::null );
/**
* The mimetype for the desired output format.
*
* This is only valid if @ref setMimeFilter() has been called
* previously.
*
* @see setMimeFilter()
*/
QString currentMimeFilter() const;
/**
* Clears any mime- or namefilter. Does not reload the directory.
*/
void clearFilter();
/**
* @deprecated
* Add a preview widget and enter the preview mode.
*
* In this mode
* the dialog is split and the right part contains your widget.
* This widget has to inherit @ref QWidget and it has to implement
* a slot @ref showPreview(const KURL &); which is called
* every time the file changes. You may want to look at
* koffice/lib/kofficecore/koFilterManager.cc for some hints :)
*
* Ownership is transferred to KFileDialog. You need to create the
* preview-widget with "new", i.e. on the heap.
*/
void setPreviewWidget(const QWidget *w);
/**
* Add a preview widget and enter the preview mode.
*
* In this mode the dialog is split and the right part contains your
* preview widget.
*
* Ownership is transferred to KFileDialog. You need to create the
* preview-widget with "new", i.e. on the heap.
*
* @param w The widget to be used for the preview.
*/
void setPreviewWidget(const KPreviewWidgetBase *w);
/**
* Create a modal file dialog and return the selected
* filename or an empty string if none was chosen.
*
* Note that with
* this method the user must select an existing filename.
*
* @param startDir This can either be
* @li The URL of the directory to start in.
* @li @ref QString::null to start in the current working
* directory, or the last directory where a file has been
* selected.
* @li ':' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li '::' to start in the directory last used
* by a filedialog in the same application that specified
* the same keyword.
* @li ':: enum Mode {
* File = 1,
* Directory = 2,
* Files = 4,
* ExistingOnly = 8,
* LocalOnly = 16
* };
*
* You can OR the values, e.g.
*
* KFile::Mode mode = static_cast( KFile::Files |
* KFile::ExistingOnly |
* KFile::LocalOnly );
* setMode( mode );
*
*/
void setMode( unsigned int m );
/**
* Retrieve the mode of the filedialog.
* @see #setMode()
*/
KFile::Mode mode() const;
/**
* Set the text to be displayed in front of the
* selection.
*
* The default is "Location".
* Most useful if you want to make clear what
* the location is used for.
*/
void setLocationLabel(const QString& text);
/**
* Retrieve a pointer to the toolbar.
*
* You can use this to insert custom
* items into it, e.g.:
*
* yourAction = new KAction( i18n("Your Action"), 0,
* this, SLOT( yourSlot() ),
* this, "action name" );
* yourAction->plug( kfileDialog->toolBar() );
*
*/
KToolBar *toolBar() const { return toolbar; }
/**
* @returns a pointer to the OK-Button in the filedialog. You may use it
* e.g. to set a custom text to it.
*/
QPushButton *okButton() const;
/**
* @returns a pointer to the Cancel-Button in the filedialog. You may use
* it e.g. to set a custom text to it.
*/
QPushButton *cancelButton() const;
signals:
/**
* Emitted when the user selects a file. It is only emitted in single-
* selection mode. The best way to get notified about selected file(s)
* is to connect to the okClicked() signal inherited from KDialogBase
* and call @ref selectedFile(), @ref selectedFiles(),
* @ref selectedURL() or @ref selectedURLs().
*/
void fileSelected(const QString&);
/**
* Emitted when the user highlights a file.
*/
void fileHighlighted(const QString&);
/**
* Emitted when the user hilights one or more files in multiselection mode.
*
* Note: @ref fileHighlighted() or @ref fileSelected() are @em not
* emitted in multiselection mode. You may use selectedItems() to
* ask for the current highlighted items.
* @see #fileSelected
*/
void selectionChanged();
/**
* Emitted when the filter changed, i.e. the user entered an own filter
* or chose one of the predefined set via @ref setFilter().
*
* @param filter contains the new filter (only the extension part,
* not the explanation), i.e. "*.cpp" or "*.cpp *.cc".
*
* @see setFilter()
* @see currentFilter()
*/
void filterChanged( const QString& filter );
protected:
KToolBar *toolbar;
static KURL *lastDirectory;
QPopupMenu *bookmarksMenu;
KURLComboBox *locationEdit;
KFileFilter *filterWidget;
KFileBookmarkManager *bookmarks;
QStringList history; // FIXME: remove it, this is not used at all
/**
* adds a entry of the current directory. If disableUpdating is set
* to true, it will care about clever updating
**/
void addDirEntry(KFileViewItem *entry, bool disableUpdating);
/**
* rebuild geometry managment.
*
*/
virtual void initGUI();
/**
* called when an item is highlighted/selected in multiselection mode.
* handles setting the locationEdit.
*/
void multiSelectionChanged();
/**
* Reads configuration and applies it (size, recent directories, ...)
*/
virtual void readConfig( KConfig *, const QString& group = QString::null );
/**
* Saves the current configuration
*/
virtual void saveConfig( KConfig *, const QString& group = QString::null );
/**
* Reads the recent used files and inserts them into the location combobox
*/
virtual void readRecentFiles( KConfig * );
/**
* Saves the entries from the location combobox.
*/
virtual void saveRecentFiles( KConfig * );
/**
* Parses the string "line" for files. If line doesn't contain any ", the
* whole line will be interpreted as one file. If the number of " is odd,
* an empty list will be returned. Otherwise, all items enclosed in " "
* will be returned as correct urls.
*/
KURL::List tokenize(const QString& line) const;
protected slots:
void urlEntered( const KURL& );
void pathComboActivated( const KURL& url );
void pathComboReturnPressed( const QString& url );
void locationActivated( const QString& url );
void toolbarCallback(int);
void toolbarPressedCallback(int); // ### remove
void slotFilterChanged();
void pathComboChanged( const QString& );
void fileHighlighted(const KFileViewItem *i);
void fileSelected(const KFileViewItem *i);
void slotStatResult(KIO::Job* job);
void slotLoadingFinished();
void dirCompletion( const QString& );
void fileCompletion( const QString& );
virtual void updateStatusLine(int dirs, int files);
virtual void slotOk();
virtual void accept();
virtual void slotCancel();
/**
* Add the current location to the global bookmarks list
*/
void addToBookmarks();
void bookmarksChanged();
void fillBookmarkMenu( KFileBookmark *parent, QPopupMenu *menu, int &id );
void addToRecentDocuments();
private slots:
void buildBookmarkPopup();
void bookmarkMenuActivated( int choice );
private:
KFileDialog(const KFileDialog&);
KFileDialog operator=(const KFileDialog&);
protected:
KFileDialogPrivate *d;
KDirOperator *ops;
bool autoDirectoryFollowing;
KURL::List& parseSelectedURLs() const;
};
#endif
| Generated by: dfaure on kde.faure.org on Thu Jan 17 22:17:38 2002, using kdoc 2.0a53. |