From 6eeefe9c3bc2ca95d359fabe64563fd86c2af9ab Mon Sep 17 00:00:00 2001 From: dogmaphobic Date: Wed, 28 Jan 2015 17:25:25 -0500 Subject: [PATCH] Documenting QGCFileDialog.h --- src/QGCFileDialog.h | 59 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/src/QGCFileDialog.h b/src/QGCFileDialog.h index 5cfd9c633..2419f9eba 100644 --- a/src/QGCFileDialog.h +++ b/src/QGCFileDialog.h @@ -27,20 +27,45 @@ #include /// @file -/// @brief Subclass of QFileDialog which re-implements the static public functions. The reason for this -/// is that the QFileDialog implementations of these use the native os dialogs. On OSX these -/// these can intermittently hang. So instead here we use the native dialogs. It also allows -/// use to catch these dialogs for unit testing. +/// @brief Subclass of QFileDialog /// @author Don Gagne +/*! + Subclass of QFileDialog which re-implements the static public functions. The reason for this + is that the QFileDialog implementations of these use the native os dialogs. On OSX these + these can intermittently hang. So instead here we use the native dialogs. It also allows + use to catch these dialogs for unit testing. +*/ + class QGCFileDialog : public QFileDialog { public: + + //! Static helper that will return an existing directory selected by the user. + /*! + \param parent The parent QWidget. + \param caption The caption displayed at the top of the dialog. + \param dir The initial directory shown to the user. + \param options Set the various options that affect the look and feel of the dialog. + \return The chosen path or QString("") if none. + \sa QFileDialog::getExistingDirectory() + */ static QString getExistingDirectory(QWidget* parent = 0, const QString& caption = QString(), const QString& dir = QString(), Options options = ShowDirsOnly); + //! Static helper that invokes a File Open dialog where the user can select a file to be opened. + /*! + \param parent The parent QWidget. + \param caption The caption displayed at the top of the dialog. + \param dir The initial directory shown to the user. + \param filter The filter used for selecting the file type. + \param selectedFilter **NOT IMPLEMENTED** Returns the filter that the user selected in the file dialog. + \param options Set the various options that affect the look and feel of the dialog. + \return The full path and filename to be opened or QString("") if none. + \sa QFileDialog::getOpenFileName() + */ static QString getOpenFileName(QWidget* parent = 0, const QString& caption = QString(), const QString& dir = QString(), @@ -48,6 +73,17 @@ public: QString* selectedFilter = 0, Options options = 0); + //! Static helper that invokes a File Open dialog where the user can select one or more files to be opened. + /*! + \param parent The parent QWidget. + \param caption The caption displayed at the top of the dialog. + \param dir The initial directory shown to the user. + \param filter The filter used for selecting the file type. + \param selectedFilter **NOT IMPLEMENTED** Returns the filter that the user selected in the file dialog. + \param options Set the various options that affect the look and feel of the dialog. + \return A QStringList object containing zero or more files to be opened. + \sa QFileDialog::getOpenFileNames() + */ static QStringList getOpenFileNames(QWidget* parent = 0, const QString& caption = QString(), const QString& dir = QString(), @@ -55,9 +91,18 @@ public: QString* selectedFilter = 0, Options options = 0); - /// @brief getSaveFileName with an extra (optional) argument to define the extension (suffix) to - /// be added if none is given by the user. If set, don't add the preceding period (i.e. - /// use "mavlink" instead of ".mavlink") + //! Static helper that invokes a File Save dialog where the user can select a directory and enter a filename to be saved. + /*! + \param parent The parent QWidget. + \param caption The caption displayed at the top of the dialog. + \param dir The initial directory shown to the user. + \param filter The filter used for selecting the file type. + \param selectedFilter **NOT IMPLEMENTED** Returns the filter that the user selected in the file dialog. + \param options Set the various options that affect the look and feel of the dialog. + \param defaultSuffix Specifies a string that will be added to the filename if it has no suffix already. The suffix is typically used to indicate the file type (e.g. "txt" indicates a text file). + \return The full path and filename to be used to save the file or QString("") if none. + \sa QFileDialog::getSaveFileName() + */ static QString getSaveFileName(QWidget* parent = 0, const QString& caption = QString(), const QString& dir = QString(), -- 2.22.0