Document public member functions for CFileDialog

src/ui/filedialog.h

@@ -35,15 +35,77 @@ class CEdit;
 class CInterface;
 
 
+/**
+ * \brief File selector dialog
+ *
+ * \section Example Example usage
+ * Create the dialog and set the type of dialog.
+ * \code
+ * CFileDialog* fileDialog = new CFileDialog();
+ * fileDialog->SetDialogType(CFileDialog::Type::Folder);
+ * \endcode
+ *
+ * Initial settings and start the dialog.
+ * \code
+ * fileDialog->SetWindowTitle("Select Player Folder");
+ * fileDialog->SetBasePath("savegame");
+ * fileDialog->StartDialog();
+ * \endcode
+ *
+ * Handle events for the dialog.
+ * \code
+ * // first check for events sent from the dialog
+ *
+ * if (event.type == EVENT_DIALOG_STOP) // cancel or close
+ * {
+ *     fileDialog->StopDialog();
+ *     delete fileDialog;
+ *     return true;
+ * }
+ *
+ * if (event.type == EVENT_DIALOG_ACTION) // ok button was pressed
+ * {
+ *     std::string folder = fileDialog->GetSubFolderPath();
+ *     fileDialog->StopDialog();
+ *     delete fileDialog;
+ *     return true;
+ * }
+ *
+ * // send the event to the dialog
+ * return m_fileDialog->EventProcess(event);
+ * \endcode
+ *
+ * \nosubgrouping
+ */
 class CFileDialog
 {
 public:
 
+    /**
+     * \brief Constructor
+     */
     CFileDialog();
+
+    /**
+     * \brief Destructor
+     */
     ~CFileDialog();
 
+    //! \name Set dialog type, starting, event processing, and stopping
+    //@{
+    /**
+     * \brief Disables other windows and creates the dialog window.
+     */
     void        StartDialog();
+
+    /**
+     * \brief Enables other windows and deletes the dialog window.
+     */
     void        StopDialog();
+
+    /**
+     * \brief Event processing.
+     */
     bool        EventProcess(const Event &event);
 
     /**
@@ -57,43 +119,157 @@ public:
         Folder,  //!< Select Folder dialog
     };
 
+    /**
+     * \brief Set the type of dialog to use.
+     */
     void              SetDialogType(CFileDialog::Type type) { m_dialogtype = type; }
+
+    /**
+     * \brief Get the type of dialog.
+     */
     CFileDialog::Type GetDialogType()                       { return m_dialogtype; }
 
-    // Set EventType for this dialog.
-    // If not set, a unique EventType will be used.
+    //@}
+
+    //! \name Dialog window properties
+    //@{
+    /**
+     * \brief Set EventType for the dialog window.
+     * If not set, a unique EventType will be used.
+     */
     void        SetWindowEvent(EventType type) { m_windowEvent = type; }
+
+    /**
+     * \brief Get EventType for the dialog window.
+     */
     EventType   GetWindowEvent()               { return m_windowEvent; }
 
+    /**
+     * \brief Set the initial position of the window.
+     */
     void        SetWindowPos(Math::Point pos) { m_windowPos = pos; }
+
+    /**
+     * \brief Get the position of the window.
+     */
     Math::Point GetWindowPos()                { return m_windowPos; }
 
+    /**
+     * \brief Set the initial size of the window.
+     */
     void        SetWindowDim(Math::Point dim) { m_windowDim = dim; }
+
+    /**
+     * \brief Get the size of the window.
+     */
     Math::Point GetWindowDim()                { return m_windowDim; }
 
+    /**
+     * \brief Set the text for the title bar of the dialog.
+     * This setting will override the default title text for the dialog.
+     */
     void        SetWindowTitle(const std::string& name) { m_title = name; }
 
+    //@}
+
+    //! \name Settings for Public and Private check boxes
+    //@{
+    /**
+     * \brief Set whether to create Public and Private check boxes.
+     * \param usePublic If true, Public and Private check boxes will be added to the dialog.
+     */
     void        SetUsePublicPrivate(bool usePublic);
+
+    /**
+     * \brief Set initial state for Public and Private check boxes.
+     * \param bPublic If true, the Public check box will be marked.
+     */
     void        SetPublic(bool bPublic);
+
+    /**
+     * \brief Get the state of Public and Private check boxes.
+     * \return true if Public check box is marked and false for Private.
+     */
     bool        GetPublic();
 
+    /**
+     * \brief Set the path for the folder associated with the Public check box.
+     * \param dir Path to 'Public' folder.
+     */
     void        SetPublicFolder(const std::string& dir);
+
+    /**
+     * \brief Set the path for the folder associated with the Private check box.
+     * \param dir Path to 'Private' folder.
+     */
     void        SetPrivateFolder(const std::string& dir);
 
+    //@}
+
+    //! \name Folder settings
+    //@{
+    /**
+     * \brief Set the initial path for the folder whose contents are displayed.
+     * This setting is overridden by Public/Private settings.
+     */
     void        SetBasePath(const std::string& dir);
+
+    /**
+     * \brief Get the initial path or Public/Private folder path
+     */
     std::string GetBasePath();
 
+    /**
+     * \brief Set the initial subfolder whose contents are displayed.
+     * \param dir Name of a subfolder. Ex. "subfolder/anotherFolder/oneMoreFolder"
+     */
     void        SetSubFolderPath(const std::string& dir);
+
+    /**
+     * \brief Get the current subfolder shown by the dialog.
+     * \return A string with a folder name and subsequent folders separated by forward slash.
+     * <p>Returns empty string if the dialog is showing GetBasePath().
+     */
     std::string GetSubFolderPath();
 
+    //@}
+
+    //! \name File name settings
+    //@{
+    /**
+     * \brief Set the extension that may be appended to a file name.
+     * <p> If any extensions are defined, the dialog will only show files
+     * with those extensions.
+     * \param ext A string with an extension. Ex. ".txt"
+     */
     void        SetAutoExtension(const std::string& ext) { m_extension = ext; }
+
+    /**
+     * \brief Define extensions that will be accepted as part of a valid file name.
+     * \param ext A string with an extension. Ex. ".txt"
+     */
     void        AddOptionalExtension(const std::string& ext) { m_extlist.push_back(ext); }
 
+    /**
+     * \brief Set the filename that appears in the edit box when the dialog opens.
+     */
     void        SetFilename(const std::string& name);
+
+    /**
+     * \brief Get the filename that was selected or typed.
+     * \return The filename that was typed in the edit box.
+     */
     std::string GetFilename();
 
+    /**
+     * \brief Set whether to check if a file exists when the 'Save' button is pressed,
+     * and if the file exists, an "Overwrite existing file?" message is shown.
+     * \param doCheck true to check if a file exists when the 'Save' button is pressed.
+     */
     void        SetConfirmOverwrite(bool doCheck) { m_confirmOverwrite = doCheck; }
 
+    //@}
+
 private:
 
     void        StartFileDialog();