|
|
Provide a user (and developer) friendly way to select files.
The widget can be used as a drop in replacement for the QFileDialog widget, but has greater functionality and a nicer GUI.
You will usually want to use one of the two static methods getOpenFileName() or getSaveFileName().
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 which will be incorporated into the layout.
enum Mode {File = 1, Directory = 2, Files = 4, Preview = 8 } |
Modes of operation for the dialog.
File
- Get a single file name from the user.
Directory
- Get a directory name from the user.
Files
- Get multiple file names from the user.
Preview
- Show a preview of the file that has the user's attention.
KFileDialog (const QString& dirName, const QString& filter, QWidget *parent, const char *name, bool modal) |
Construct a KFileDialog
Parameters:
dirName | The name of the directory to start in. |
filter | A shell glob that specifies which files to display. see setFilter for details on how to use this argument |
acceptURLs | If set to false, KFileDialog will just accept files on the local filesystem. |
~KFileDialog () |
Clean up.
KURL selectedURL () |
Retrieve the fully qualified filename.
KURL baseURL () |
Retrieve the current directory.
QString selectedFile () |
Returns: Full path in local filesystem. (Local files only)
void setURL (const QString& name, bool clearforward = true) |
Set the directory to view.
Parameters:
name | URL to show |
clearforward | Indicate whether the forward queue should be cleared. |
void setURL (const KURL &url, bool clearforward = true) |
Set the directory to view.
Parameters:
name | URL to show |
clearforward | Indicate whether the forward queue should be cleared. |
void setSelection (const QString& name) |
Set the filename to preselect.
This takes absolute and relative file names.
void setFilter (const QString& filter) |
Set the filter to be used to filter.
You can set more filters for the user to select seperated by '\n'. Every filter entry is defined through namefilter|text to diplay. If no | is found in the expression, just the namefilter is shown. Examples:
kfile->setFilter("*.cpp|C++ Source Files\n*.h|Header files"); kfile->setFilter("*.cpp"); kfile->setFilter("*.cpp|Sources (*.cpp)");
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.
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 widget. This widget has to inherit QWidget and it has to implement a slot 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 :)
QString getOpenFileName (const QString& dir= QString::null, const QString& filter= QString::null, QWidget *parent= 0, const QString& caption = QString::null) |
Thi method creates a modal file dialog and returns the selected filename or an empty string if none was chosen.
Note that with this method the user must select an existing filename.
Parameters:
dir | This specifies the path the dialog will start in. |
filter | This is a space seperated list of shell globs. |
parent | The widget the dialog will be centered on initially. |
name | The name of the dialog widget. |
QString getSaveFileName (const QString& dir= QString::null, const QString& filter= QString::null, QWidget *parent= 0, const QString& caption = QString::null) |
Creates a modal file dialog and returns the selected filename or an empty string if none was chosen.
Note that with this method the user need not select an existing filename.
Parameters:
dir | This specifies the path the dialog will start in. |
filter | This is a space seperated list of shell globs. |
parent | The widget the dialog will be centered on initially. |
caption | The name of the dialog widget. |
QString getExistingDirectory (const QString & dir = QString::null, QWidget * parent = 0, const QString& caption = QString::null) |
Creates a modal file dialog and returns the selected directory or an empty string if none was chosen.
Note that with this method the user need not select an existing directory.
Parameters:
dir | The directory the dialog will start in. |
parent | The widget the dialog will be centered on initially. |
caption | The name of the dialog widget. |
void show () |
Show the widget.
void setMode ( Mode m ) |
Set the mode of the dialog.
Mode mode () |
Retrieve the mode of the filedialog.
void setLocationLabel (const QString& text) |
sets 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 setEnableChdir ( bool enable ) |
KFileDialog uses chhdir() to change the current working directory to increase performance. If you don't like this, disable it.
When using one of the static methods, e.g. getOpenFileName, and chdir is enabled, the working directory will be restored when the dialog is closed. Default is enabled.
bool isChdirEnabled () |
Returns: whether KFileDialog changes the current working directory (via chdir()).
void fileSelected (const QString&) |
Emitted when the user selects a file.
void fileHighlighted (const QString&) |
Emitted when the user highlights a file.
void historyUpdate (bool, bool) |
Emitted when the allowable history operations change.
void addDirEntry (KFileViewItem *entry, bool disableUpdating) |
adds a entry of the current directory. If disableUpdating is set to true, it will care about clever updating
void initGUI () |
rebuild geometry managment.
void checkPath (const QString& txt, bool takeFiles = false) |
takes action on the new location. If it's a directory, change into it, if it's a file, correct the name, etc.
Parameters:
takeFiles | if set to true, if will close the dialog, if txt is a file name |
void addToBookmarks () |
Add the current location to the global bookmarks list