From cf588777067fde12b620060b4bbbd857cb89ceb1 Mon Sep 17 00:00:00 2001 From: post-rick Date: Thu, 25 Apr 2019 20:08:35 +0100 Subject: [PATCH] Add documentation for GUI functions --- Doxyfile | 2 +- README.md | 7 +- include/matrix.h | 2 +- src/gui/clipdialog.h | 68 +++++++++++-- src/gui/helpdialog.h | 3 + src/gui/mainwindow.h | 237 +++++++++++++++++++++++++++++++++++++++++-- src/matrix.cpp | 2 +- 7 files changed, 302 insertions(+), 19 deletions(-) diff --git a/Doxyfile b/Doxyfile index 911ed07..e63b87c 100644 --- a/Doxyfile +++ b/Doxyfile @@ -2537,4 +2537,4 @@ DOT_CLEANUP = YES # Parse header files -INPUT = $(TRAVIS_BUILD_DIR)/include $(TRAVIS_BUILD_DIR)/src \ No newline at end of file +INPUT = $(TRAVIS_BUILD_DIR)/include $(TRAVIS_BUILD_DIR)/src $(TRAVIS_BUILD_DIR)/src/gui \ No newline at end of file diff --git a/README.md b/README.md index be659b2..99332a4 100644 --- a/README.md +++ b/README.md @@ -129,9 +129,10 @@ runs the ```.travis.yml``` configuration on a hosted environment (generally a virtual machine running Linux, specifically Ubuntu) and sends you an email in case the latest commit breaks the tests in any way. -# Useful info - -- A cell is a shape (e.g. tetrahedron) +# Possible future implementations +- Code could be cleaned up, especially in mainwindow.cpp. +The different functions could be put in different files, +improving the ease of navigating the GUI source code. ## Useful links diff --git a/include/matrix.h b/include/matrix.h index 08e0b5b..449ab8f 100644 --- a/include/matrix.h +++ b/include/matrix.h @@ -1,6 +1,6 @@ /** * @file matrix.h - * @brief Header file for the Matrix class + * @brief Header file for the Matrix3x3 class * @author Riccardo Di Maio * @version 1.0 14/12/18 */ diff --git a/src/gui/clipdialog.h b/src/gui/clipdialog.h index a256d1d..db0013d 100644 --- a/src/gui/clipdialog.h +++ b/src/gui/clipdialog.h @@ -10,39 +10,93 @@ #include -namespace Ui { - class ClipDialog; +namespace Ui +{ +class ClipDialog; } +/** + * Clip filter dialog. + * As MainWindow cannot access ClipDialog's objects (e.g. xSlider, yDial) + * directly, custom signals are used to be emitted and picked up by MainWindow. + */ class ClipDialog : public QDialog { Q_OBJECT -signals: + signals: + /** + * Signal emitted when the x slider is moved + */ void xSliderMoved(int value); + /** + * Signal emitted when the y slider is moved + */ void ySliderMoved(int value); + /** + * Signal emitted when the z slider is moved + */ void zSliderMoved(int value); + /** + * Signal emitted when the x dial is moved + */ void xDialMoved(int value); + /** + * Signal emitted when the y dial is moved + */ void yDialMoved(int value); + /** + * Signal emitted when the z dial is moved + */ void zDialMoved(int value); + /** + * Signal emitted when the OK button is clicked + */ void clipDialogRejected(); + /** + * Signal emitted when the Cancel button is clicked + */ void clipDialogAccepted(); -public: + public: explicit ClipDialog(QWidget *parent = nullptr); ~ClipDialog(); -private slots: + private slots: + /** + * Slot handling the sliderMoved signal from the x slider + */ void on_xSlider_sliderMoved(int position); + /** + * Slot handling the sliderMoved signal from the y slider + */ void on_ySlider_sliderMoved(int position); + /** + * Slot handling the sliderMoved signal from the z slider + */ void on_zSlider_sliderMoved(int position); + /** + * Slot handling the sliderMoved signal from the x dial + */ void on_xDial_sliderMoved(int position); + /** + * Slot handling the sliderMoved signal from the y dial + */ void on_yDial_sliderMoved(int position); + /** + * Slot handling the sliderMoved signal from the z dial + */ void on_zDial_sliderMoved(int position); - void on_clipDialog_rejected(); + /** + * Slot handling the OK button + */ void on_clipDialog_accepted(); + /** + * Slot handling the Cancel button + */ + void on_clipDialog_rejected(); -private: + private: Ui::ClipDialog *ui; }; diff --git a/src/gui/helpdialog.h b/src/gui/helpdialog.h index 358f08b..42a879b 100644 --- a/src/gui/helpdialog.h +++ b/src/gui/helpdialog.h @@ -14,6 +14,9 @@ namespace Ui{ class HelpDialog; } +/** + * Help dialog that displays information regarding 13CAD. + */ class HelpDialog : public QDialog { Q_OBJECT diff --git a/src/gui/mainwindow.h b/src/gui/mainwindow.h index 3e6b3c5..50bded0 100644 --- a/src/gui/mainwindow.h +++ b/src/gui/mainwindow.h @@ -29,6 +29,9 @@ namespace Ui { class MainWindow; } +/** + * Main GUI window. + */ class MainWindow : public QMainWindow { Q_OBJECT @@ -36,6 +39,10 @@ class MainWindow : public QMainWindow ClipDialog *clipWindow = nullptr; signals: + + /** + * Signal emitted when a message is displayed in the status bar + */ void statusUpdateMessage(const QString &message, int timeout); public: @@ -43,95 +50,313 @@ class MainWindow : public QMainWindow ~MainWindow(); private: + Ui::MainWindow *ui; + + /** + * Setup function for the window + */ void setupWindow(); + + /** + * Setup function that handles which buttons are enabled when the model is loaded + */ void setupButtons(bool modelLoaded); + + /** + * Setup function that connects icons to their respective QActions + */ void setupIcons(); + + /** + * Setup function that connects signals to their respective slots + */ void setupConnects(); + /** - * Loads model. - */ + * Loads model + */ void loadModel(QString inputFilename); + /** - * Clears loaded model. - */ + * Clears loaded model + */ void clearModel(); + /** + * Resets camera + */ void resetCamera(); public slots: + + /** + * Handles file opening + */ void handleActionOpen(); + + /** + * Handles file saving + */ void handleActionSave(); + + /** + * Handles file closing + */ void handleActionClose(); + + /** + * Handles the screenshot function + */ void handleActionPrint(); + + /** + * Handles the toggling of external light + */ void handleActionEnableIntensity(); + + /** + * Handles the toggling of the coordinate axes + */ void handleActionShowAxes(); + + /** + * Handles the full screen function + */ void handleActionFullScreen(); + + /** + * Handles the export data function + */ void handleActionExportData(); + + /** + * Handles the about function, creates help dialog + */ void handleActionAbout(); + + /** + * Handles the reset filters function + */ void handleActionResetFilters(); + + /** + * Handles the reset camera function + */ void handleActionResetCamera(); + + /** + * Handles the reset lighting function + */ void handleActionResetLighting(); + + /** + * Handles the reset properties function + */ void handleActionResetProperties(); + + /** + * Loads a test .STL file + */ void handleActionStlTest(); + + /** + * Loads a test .mod file + */ void handleActionModTest(); private slots: + // Filters + + /** + * Enables shrink filter + */ void on_shrinkButton_clicked(); + + /** + * Enables clip filter + */ void on_clipButton_clicked(); + + /** + * Resets filters + */ void on_resetFiltersButton_clicked(); // Properties + + /** + * Shows colour dialog, allows the user to change background colour + */ void on_bkgColourButton_clicked(); + + /** + * Toggle between gradient and non-gradient background + */ void on_gradientCheckBox_stateChanged(int state); + + /** + * Shows colour dialog, allows the user to change model colour + */ void on_modColourButton_clicked(); + + /** + * Resets colours + */ void on_resetPropertiesButton_clicked(); // Lighting - // Note on opacity slider: + // Note on opacity and specularity sliders: // If a STL model is loaded, there is only one actor, // thus changing the opacity as the slider is moved // is not resource expensive. // If a MOD model is loaded, there will be many actors, // thus the opacity is only changed when the value is changed. + + /** + * Changes opacity of .stl models as the slider is moved + */ void on_opacitySlider_sliderMoved(int position); + + /** + * Changes opacity of .mod models after the slider is released + */ void on_opacitySlider_valueChanged(int value); + /** + * Changes specularity of .stl models as the slider is moved + */ void on_specularitySlider_sliderMoved(int position); + + /** + * Changes specularity of .mod models after the slider is released + */ void on_specularitySlider_valueChanged(int value); + /** + * Changes intensity of external light as the slider is moved + */ void on_intensitySlider_sliderMoved(int position); + + /** + * Toggles external light + */ void on_intensityCheckBox_stateChanged(int state); + + /** + * Toggles coordinate axes + */ void on_showAxesCheckBox_stateChanged(int state); + /** + * Resets lighting + */ void on_resetLightingButton_clicked(); + /** + * Changes X parameter of clip plane for the clip filter + */ void on_clipXSlider_sliderMoved(int position); + + /** + * Changes Y parameter of clip plane for the clip filter + */ void on_clipYSlider_sliderMoved(int position); + + /** + * Changes Z parameter of clip plane for the clip filter + */ void on_clipZSlider_sliderMoved(int position); + + /** + * Changes X parameter of the rotation of the clip plane for the clip filter + */ void on_clipXDial_sliderMoved(int position); + + /** + * Changes Y parameter of the rotation of the clip plane for the clip filter + */ void on_clipYDial_sliderMoved(int position); + + /** + * Changes Z parameter of the rotation of the clip plane for the clip filter + */ void on_clipZDial_sliderMoved(int position); + + /** + * Accepts new clip filter's parameters, closes clip dialog + */ + void on_clipDialog_dialogAccepted(); + + /** + * Resets clip filter's parameters to previous state + */ void on_clipDialog_dialogRejected(); - void on_clipDialog_dialogAccepted(); // Camera // Note for the camera functions: // The view up vector must be set to be orthogonal to the camera direction. + /** + * Resets camera + */ void on_resetCameraButton_clicked(); + + /** + * Sets camera on the X axis + */ void on_posXButton_clicked(); + + /** + * Sets camera on the Y axis + */ void on_posYButton_clicked(); + + /** + * Sets camera on the Z axis + */ void on_posZButton_clicked(); + + /** + * Rotates camera clockwise 90 degrees + */ void on_pos90Button_clicked(); + + /** + * Sets camera on the negative X axis + */ void on_negXButton_clicked(); + + /** + * Sets camera on the negative Y axis + */ void on_negYButton_clicked(); + + /** + * Sets camera on the negative Z axis + */ void on_negZButton_clicked(); + + /** + * Rotates camera counter-clockwise 90 degrees + */ void on_neg90Button_clicked(); // Visualization + + /** + * Toggles wireframe visualization + */ void on_wireframeRadio_toggled(bool checked); + + /** + * Toggles points visualization + */ void on_pointsRadio_toggled(bool checked); + + /** + * Toggles surface (default) visualization + */ void on_surfaceRadio_toggled(bool checked); }; diff --git a/src/matrix.cpp b/src/matrix.cpp index 9095ac1..fdeee31 100644 --- a/src/matrix.cpp +++ b/src/matrix.cpp @@ -1,6 +1,6 @@ /** * @file matrix.cpp - * @brief Source file for the Matrix class + * @brief Source file for the Matrix3x3 class * @author Riccardo Di Maio * @version 1.0 14/12/18 */