Difference between revisions of "File dialog"

From Trinity Desktop Project Wiki
Jump to navigation Jump to search
imported>Eliddell
(Created page with "KDE's file dialogs are implemented in the kfile library, which also contains other widgets. == File Dialog == The classes related to the file dialog are really a file dialog...")
 
m (Blu256 moved page File dialog (KDE3 Architecture) to File dialog: Simpler name)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Image:k3filedialog-widgets.png|thumb|400px|KFileDialog widgets]]
KDE's file dialogs are implemented in the kfile library, which also
 
  +
 
Trinity's '''file dialogs''' are implemented in the ''tdefile'' library, which also
 
contains other widgets.
 
contains other widgets.
   
Line 6: Line 8:
 
The classes related to the file dialog are really a file dialog construction
 
The classes related to the file dialog are really a file dialog construction
 
set, i.e. the API not only contain the class
 
set, i.e. the API not only contain the class
[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKFileDialog.html KFileDialog]
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKFileDialog.html KFileDialog]
 
with its conveniently usable functions to obtain file names for saving or
 
with its conveniently usable functions to obtain file names for saving or
 
opening, but it also offers the various single widgets that constitute the
 
opening, but it also offers the various single widgets that constitute the
 
dialog for separate use.
 
dialog for separate use.
 
[[Image:k3filedialog-widgets.png|thumb|center|500px|KFileDialog widgets]]
 
   
 
=== KDirOperator ===
 
=== KDirOperator ===
   
 
The main view of the file dialog is a
 
The main view of the file dialog is a
[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKDirOperator.html KDirOperator].
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKDirOperator.html KDirOperator].
 
It is a general browser for files and directories. How these lists and
 
It is a general browser for files and directories. How these lists and
 
trees are actually represented is configurable by the user. All widgets
 
trees are actually represented is configurable by the user. All widgets
possible for this are derived from the class KFileView. These are the
+
possible for this are derived from the class [http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKFileView.html KFileView]. These are the
 
following:
 
following:
   
*[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKFileIconView.html KFileIconView]: Corresponds to selecting "Short view" and "Single view" from the View submenu.
+
*[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKFileIconView.html KFileIconView]: Corresponds to selecting "Short view" and "Single view" from the View submenu.
*[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKFileDetailView.html KFileDetailView]: Corresponds to selecting "Detailed view" and "Single view" from the View submenu.
+
*[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKFileDetailView.html KFileDetailView]: Corresponds to selecting "Detailed view" and "Single view" from the View submenu.
*[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKCombiView.html KCombiView]: Corresponds to selecting "Separate directories" from the View submenu. This is a splitter widget which displays a KFileIconView (see above) on the left side and either a KFileIconView (if "Short view" is selected) or a KFileDetailView (if "Detailed view" is selected) on the right side.
+
*[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKCombiView.html KCombiView]: Corresponds to selecting "Separate directories" from the View submenu. This is a splitter widget which displays a KFileIconView (see above) on the left side and either a KFileIconView (if "Short view" is selected) or a KFileDetailView (if "Detailed view" is selected) on the right side.
*[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKFilePreview.html KFilePreview]: Corresponds to selecting "Preview" from the View submenu. This is also a splitter, which shows a KFileIconView (if "Short view" is selected) or a KFileDetailView (if "Detailed view" is selected) on the left side and a widget derived from KPreviewWidgetBase on the right side. By default, the widget on the right side is a KImagePreviewWidget, but this can be changed. This should be very rarely necessary, because the KImagePreviewWidget uses a mechanism for obtaining preview images (also known as ''thumbnails'') which can be extended by installing additional ThumbCreator services. In this way, the same preview images can also be used by Konqueror's icon view.
+
*[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKFilePreview.html KFilePreview]: Corresponds to selecting "Preview" from the View submenu. This is also a splitter, which shows a KFileIconView (if "Short view" is selected) or a KFileDetailView (if "Detailed view" is selected) on the left side and a widget derived from KPreviewWidgetBase on the right side. By default, the widget on the right side is a KImagePreviewWidget, but this can be changed. This should be very rarely necessary, because the KImagePreviewWidget uses a mechanism for obtaining preview images (also known as ''thumbnails'') which can be extended by installing additional ThumbCreator services. In this way, the same preview images can also be used by Konqueror's icon view.
   
 
=== KURLComboBox ===
 
=== KURLComboBox ===
Line 37: Line 37:
   
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
KURL u(QDir::homeDirPath());
+
KURL u(TQDir::homeDirPath());
QString text = i18n("Home Directory");
+
TQString text = i18n("Home Directory");
QPixmap pixmap = KMimeType::pixmapForURL(u, 0, KIcon::Small);
+
TQPixmap pixmap = KMimeType::pixmapForURL(u, 0, TDEIcon::Small);
 
combobox->addDefaultURL(u, pixmap, text);
 
combobox->addDefaultURL(u, pixmap, text);
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 59: Line 59:
   
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
QStringList mimeTypes;
+
TQStringList mimeTypes;
 
mimeTypes << "image/png";
 
mimeTypes << "image/png";
 
mimeTypes << "text/html";
 
mimeTypes << "text/html";
Line 73: Line 73:
   
 
This is a subclass of
 
This is a subclass of
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKCompletion.html KCompletion]
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDECompletion.html TDECompletion]
 
and specifically designed to provide automatic completions for URLs.
 
and specifically designed to provide automatic completions for URLs.
 
It can operate in one of two modes: <tt>ExeCompletion</tt> completes names
 
It can operate in one of two modes: <tt>ExeCompletion</tt> completes names
Line 81: Line 81:
   
 
Completion support can easily be added to line edits (derived from
 
Completion support can easily be added to line edits (derived from
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdeui/html/classKLineEdit.html KLineEdit])
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdeui/html/classKLineEdit.html KLineEdit])
 
or combo boxes (derived from
 
or combo boxes (derived from
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdeui/html/classKComboBox.html KComboBox]):
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdeui/html/classKComboBox.html KComboBox]):
   
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
KCompletion *completion =
+
TDECompletion *completion =
 
new KURLCompletion(KURLCompletion::ExeCompletion);
 
new KURLCompletion(KURLCompletion::ExeCompletion);
 
lineEdit->setCompletionObject(completion);
 
lineEdit->setCompletionObject(completion);
Line 95: Line 95:
   
 
This is a subclass of
 
This is a subclass of
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKPixmapProvider.html KPixmapProvider]
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classKPixmapProvider.html KPixmapProvider]
 
which resolves pixmaps for URLs.
 
which resolves pixmaps for URLs.
   
 
Support for URL icons in combo boxes (derived from
 
Support for URL icons in combo boxes (derived from
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdeui/html/classKComboBox.html KComboBox])
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdeui/html/classKComboBox.html KComboBox])
 
can be easily added:
 
can be easily added:
   
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
KPixmapProver *pixmapProvider = new KURLPixmapProvider();
+
KPixmapProvider *pixmapProvider = new KURLPixmapProvider();
 
comboBox->setPixmapProvider(pixmapProvider);
 
comboBox->setPixmapProvider(pixmapProvider);
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 116: Line 116:
 
A simple dialog for letting the user input a file name or URL. It is
 
A simple dialog for letting the user input a file name or URL. It is
 
a very thin wrapper around the KURLRequester widget. For example, this
 
a very thin wrapper around the KURLRequester widget. For example, this
is used when you choose "Location->Open Location" in Konqueror.
+
is used when you choose <code>Location → Open Location</code> in Konqueror.
   
 
=== KOpenWithDlg ===
 
=== KOpenWithDlg ===
Line 128: Line 128:
 
Konqueror's context menu or the context menu in the file dialog. The
 
Konqueror's context menu or the context menu in the file dialog. The
 
dialog can be extended with more tabs by inserting additional
 
dialog can be extended with more tabs by inserting additional
[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kfile/html/classKPropsDlgPlugin.html KPropsDlgPlugin])
+
[http://trinitydesktop.org/docs/trinity/tdelibs/tdeio/tdefile/html/classKPropsDlgPlugin.html KPropsDlgPlugin])
 
widgets.
 
widgets.
   
Line 135: Line 135:
 
A dialog for selecting icons.
 
A dialog for selecting icons.
   
  +
Furthermore, a number of additional IO jobs:
 
  +
----
  +
 
Furthermore, there is a number of additional IO jobs:
   
 
=== KDirSize ===
 
=== KDirSize ===
Line 145: Line 148:
 
A class for finding out the free disk space on a disk.
 
A class for finding out the free disk space on a disk.
   
=== KIO::PreviewJob ===
+
=== TDEIO::PreviewJob ===
   
 
A job for creating thumbnails for a set of files.
 
A job for creating thumbnails for a set of files.

Latest revision as of 15:40, 21 April 2022

KFileDialog widgets

Trinity's file dialogs are implemented in the tdefile library, which also contains other widgets.

File Dialog

The classes related to the file dialog are really a file dialog construction set, i.e. the API not only contain the class KFileDialog with its conveniently usable functions to obtain file names for saving or opening, but it also offers the various single widgets that constitute the dialog for separate use.

KDirOperator

The main view of the file dialog is a KDirOperator. It is a general browser for files and directories. How these lists and trees are actually represented is configurable by the user. All widgets possible for this are derived from the class KFileView. These are the following:

  • KFileIconView: Corresponds to selecting "Short view" and "Single view" from the View submenu.
  • KFileDetailView: Corresponds to selecting "Detailed view" and "Single view" from the View submenu.
  • KCombiView: Corresponds to selecting "Separate directories" from the View submenu. This is a splitter widget which displays a KFileIconView (see above) on the left side and either a KFileIconView (if "Short view" is selected) or a KFileDetailView (if "Detailed view" is selected) on the right side.
  • KFilePreview: Corresponds to selecting "Preview" from the View submenu. This is also a splitter, which shows a KFileIconView (if "Short view" is selected) or a KFileDetailView (if "Detailed view" is selected) on the left side and a widget derived from KPreviewWidgetBase on the right side. By default, the widget on the right side is a KImagePreviewWidget, but this can be changed. This should be very rarely necessary, because the KImagePreviewWidget uses a mechanism for obtaining preview images (also known as thumbnails) which can be extended by installing additional ThumbCreator services. In this way, the same preview images can also be used by Konqueror's icon view.

KURLComboBox

This is a combo box for selecting from a number of files and directories. It runs in one of three modes. The KURLComboBox at the top of the file dialog is in "Directories" mode, the one at the bottom in "Files" mode. Items in the popup menu are shown as URLs together with their MIME type icon. Additionally, one can add a number of default items which are shown as clear text. For example:

KURL u(TQDir::homeDirPath());
TQString text = i18n("Home Directory");
TQPixmap pixmap = KMimeType::pixmapForURL(u, 0, TDEIcon::Small);
combobox->addDefaultURL(u, pixmap, text);

KFileFilter

This is a combo box for selecting from a number of file filters or MIME types. There are two ways to populate it with items:

First, you can give a linebreak-separated list of strings of the following form:

combo->setFilter("*.cpp|Implementation files\n*.h|Header files");

This displays the clear text strings in the popup in order to select the according patterns. The other method is to give a list of MIME types:

TQStringList mimeTypes;
mimeTypes << "image/png";
mimeTypes << "text/html";
combo->setMimeFilter(mimeTypes);

Other widgets

Apart from the widgets used in the file dialog, there is a number of related classes (partially contained in the ksycoca library):

KURLCompletion

This is a subclass of TDECompletion and specifically designed to provide automatic completions for URLs. It can operate in one of two modes: ExeCompletion completes names of executables by searching them in $PATH (if they are not given as absolute file names). FileCompletion completes generic URLs. This works even for remote addresses.

Completion support can easily be added to line edits (derived from KLineEdit) or combo boxes (derived from KComboBox):

TDECompletion *completion =
    new KURLCompletion(KURLCompletion::ExeCompletion);
lineEdit->setCompletionObject(completion);
lineEdit->setAutoDeleteCompletionObject(true);

KURLPixmapProvider

This is a subclass of KPixmapProvider which resolves pixmaps for URLs.

Support for URL icons in combo boxes (derived from KComboBox) can be easily added:

KPixmapProvider *pixmapProvider = new KURLPixmapProvider();
comboBox->setPixmapProvider(pixmapProvider);

KURLRequester

This is a lineedit combined with a button that invokes a file dialog. It uses the KURLCompletion class described above.

KURLRequesterDlg

A simple dialog for letting the user input a file name or URL. It is a very thin wrapper around the KURLRequester widget. For example, this is used when you choose Location → Open Location in Konqueror.

KOpenWithDlg

The dialog shown by Konqueror when you click on a file with unknown MIME type.

KPropertiesDialog

The properties dialog you get when you choose the "Properties" item from Konqueror's context menu or the context menu in the file dialog. The dialog can be extended with more tabs by inserting additional KPropsDlgPlugin) widgets.

KIconDialog

A dialog for selecting icons.



Furthermore, there is a number of additional IO jobs:

KDirSize

This computes the sum of the file sizes in a directory.

KDiskFreeSp

A class for finding out the free disk space on a disk.

TDEIO::PreviewJob

A job for creating thumbnails for a set of files.


Initial Author: Bernd Gehrmann