Refactoring and documentation

LenaPi/EnergySaver.cpp

@@ -4,16 +4,6 @@
 #include <QProcess>
 #include <iostream>
 
-EnergySaver::EnergySaver(QObject *parent) : QObject(parent)
-{
-
-}
-
-/**
- * @brief Create instance if necessary and set timeout interval.
- * @param interval Timer interval in seconds
- * @see EnergySaver::instance
- */
 void EnergySaver::init(int interval)
 {
     EnergySaver* saver = instance();
@@ -22,12 +12,7 @@ void EnergySaver::init(int interval)
 }
 
 
-/**
+
- * @brief Implements the singleton pattern.
- * @return Instance
- *
- * If no instance has been created yet, create new instance.
- */
 EnergySaver *EnergySaver::instance()
 {
     static EnergySaver* inst;
@@ -46,10 +31,7 @@ void EnergySaver::restartTimer()
     mTimer.start();
 }
 
-/**
+
- * @brief Initialize and connect timer.
- * @param interval Timeout interval in millisecond.
- */
 void EnergySaver::initTimer(int interval)
 {
     connect(&mTimer, &QTimer::timeout, this, &EnergySaver::onTimeout);
@@ -57,9 +39,7 @@ void EnergySaver::initTimer(int interval)
     mTimer.setSingleShot(true);
 }
 
-/**
+
- * @brief Behavior on timeout: shut down RaspberryPi.
- */
 void EnergySaver::onTimeout()
 {
     std::cout << "Shutting down.";

LenaPi/EnergySaver.h

@@ -7,29 +7,54 @@
 /**
  * @brief Class handling energy saving options.
  *
- * Shut down RaspberryPi if no mouse input is detected and music player
+ * Shut down device if no mouse input is detected and music player
  * has not been active or a certain time interval.
+ *
+ * @todo For now this does only work for Lena's RasPi, where the
+ * shutdown script is positioned in a ceratin hardcoded path.
+ * Enable/disable energy saving option, timeout and path of
+ * shutdown script via config
  */
 class EnergySaver : public QObject
 {
     Q_OBJECT
 
 protected:
-    EnergySaver(QObject *parent = 0);
+    explicit EnergySaver(QObject *parent = nullptr) : QObject(parent) {};
 
 public:
-
+    /**
+     * @brief Create instance if necessary and set timeout interval.
+     * @param interval Timer interval in seconds
+     * @see EnergySaver::instance
+     */
     static void init(int interval);
+    /**
+     * @brief Implements the singleton pattern.
+     * @return Instance
+     *
+     * If no instance has been created yet, create new instance.
+     */
     static EnergySaver *instance();
 
 public slots:
+    /**
+     * @brief Restart shutdown timer, e.g. because of music player activiti
+     */
     void restartTimer();
 
 private:
+    /**
+     * @brief Initialize and connect timer.
+     * @param interval Timeout interval in millisecond.
+     */
     void initTimer(int interval);
     QTimer mTimer;
 
 private slots:
+    /**
+     * @brief Behavior on timeout: shut down RaspberryPi.
+     */
     void onTimeout();
 
 };

LenaPi/LenaPi.pro.user

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE QtCreatorProject>
-<!-- Written by QtCreator 4.8.2, 2021-03-13T17:07:20. -->
+<!-- Written by QtCreator 4.8.2, 2021-03-14T14:48:57. -->
 <qtcreator>
  <data>
   <variable>EnvironmentId</variable>

LenaPi/MouseEventSpy.cpp

@@ -3,30 +3,12 @@
 #include <QGuiApplication>
 #include <QDebug>
 
-MouseEventSpy::MouseEventSpy(QObject *parent) : QObject(parent)
-{
-}
-
-/**
- * @brief Create instance if necessary.
- *
- * If no instance has been created yet, create new instance and install it as event filter
- * in QGuiApplication.
- *
- * @see MouseEventSpy::instance()
- */
 void MouseEventSpy::init()
 {
     instance();
 }
 
-/**
+
- * @brief Implements the singleton pattern.
- * @return Instance
- *
- * If no instance has been created yet, create new instance and install it as event filter
- * in QGuiApplication.
- */
 MouseEventSpy* MouseEventSpy::instance()
 {
     static MouseEventSpy* inst;
@@ -39,28 +21,20 @@ MouseEventSpy* MouseEventSpy::instance()
     return inst;
 }
 
-/**
+
- * @brief Expand QObject::eventFilter to react to MouseEvents.
- *
- * Restart timer each time a mouse event is detected.
- */
 bool MouseEventSpy::eventFilter(QObject* watched, QEvent* event)
 {
     QEvent::Type t = event->type();
     if (isMouseEvent(t)
-            && event->spontaneous() // Take only mouse events from outside of Qt
+         && event->spontaneous() // Take only mouse events from outside of Qt
-            )
+     )
     {
         emit mouseEventDetected();
     }
     return QObject::eventFilter(watched, event);
 }
 
-/**
+
- * @brief Checks whether the event type is a mouse event.
- * @param t Event type
- * @return Returns whether the event type is a mouse event.
- */
 bool MouseEventSpy::isMouseEvent(QEvent::Type t)
 {
     return (t == QEvent::MouseButtonDblClick

LenaPi/MouseEventSpy.h

@@ -15,19 +15,44 @@ class MouseEventSpy : public QObject
     Q_OBJECT
 
 protected:
-    explicit MouseEventSpy(QObject *parent = 0);
+    explicit MouseEventSpy(QObject *parent = nullptr) : QObject(parent) { /* nothing */ }
 
 signals:
     void mouseEventDetected();
 
 public:
+    /**
+     * @brief Create instance if necessary.
+     *
+     * If no instance has been created yet, create new instance and install it as event filter
+     * in QGuiApplication.
+     *
+     * @see MouseEventSpy::instance()
+     */
     static void init();
+    /**
+     * @brief Implements the singleton pattern.
+     * @return Instance of MouseEventSpy
+     *
+     * If no instance has been created yet, create new instance and install it as event filter
+     * in QGuiApplication.
+     */
     static MouseEventSpy* instance();
 
 protected:
+    /**
+     * @brief Expand QObject::eventFilter to react to MouseEvents.
+     *
+     * Restart timer each time a mouse event is detected.
+     */
     bool eventFilter(QObject* watched, QEvent* event);
 
 private:
+    /**
+     * @brief Checks whether the event type is a mouse event.
+     * @param t Event type
+     * @return Returns whether the event type is a mouse event.
+     */
     bool isMouseEvent(QEvent::Type t);
 
 };

LenaPi/models/NavigationItemModel.cpp

@@ -69,7 +69,7 @@ QList<NavigationItemModel *> NavigationItemModel::getChildren()
 QList<NavigationItemModel *> NavigationItemModel::getSiblings()
 {
     if(isRoot()){
-        return QList<NavigationItemModel*>();
+        return QList<NavigationItemModel *>();
     } else{
         return mParentItem->getChildren();
     }

LenaPi/models/NavigationItemModel.h

@@ -3,6 +3,16 @@
 
 #include <QObject>
 
+/**
+ * @brief Model for navigation item.
+ *
+ * Each item represents a directory that is specified by path.
+ * It contains a reference to its parent item as well as to its children.
+ * Each directory contains an image named image.jpg that is displayed on
+ * on the list delegate.
+ * A delegate is circular if it has children and rectangular if it is
+ * a leaf, i.e., if it represents a music folder.
+ */
 class NavigationItemModel : public QObject
 {
     Q_OBJECT
@@ -16,34 +26,89 @@ signals:
     void clicked();
 
 public:
-    NavigationItemModel(QObject *parent = Q_NULLPTR);
+    explicit NavigationItemModel(QObject *parent = nullptr);
 
+    /**
+     * @brief Get source of image displayed on delegate.
+     * @return Source of image
+     *
+     * The image must be named image.jpg and must be postioned in the directory
+     * represented by this item. If no such image is found, a default image is displayed
+     * on the delegate.
+     */
     QString getImageSource() const;
 
+    /**
+     * @brief Get path to folder represented by this navigation item.
+     * @return Path to folder
+     */
     QString getPath() const;
+    /**
+     * @brief Set folder path and set image source displayed on delegate.
+     * @param path Path to directory that is represented by this navigation item.
+     * @return returns false if directory specified by path does not exist
+     */
     bool setPath(const QString & path);
 
+    /**
+     * @brief Indicates whether this item is displayed as a circular or default delegate in navigation list.
+     * @return true if the current item is displayed as a circular delegate.
+     *
+     * An item is displayed as a circular delegate if it has children.
+     */
     bool isCircleDelegate() const;
-    void setCircleDelegate(bool value);
 
+    /**
+     * @brief Indicates whether the current item is the root item of the navigation.
+     * @return true if the current item is the root item.
+     */
     bool isRoot() const;
+    /**
+     * @brief Get pointer to parent item.
+     * @return Pointer to parent item.
+     */
     NavigationItemModel* getParentItem();
 
+    /**
+     * @brief Indicates whether the current item has children.
+     * @return false if children list is empty, true otherwise.
+     */
     bool hasChildren() const;
+    /**
+     * @brief Get all child items
+     * @return List of child items
+     */
     QList<NavigationItemModel *> getChildren();
 
+    /**
+     * @brief Get all siblings, i.e., all children of parent item.
+     * @return List of all siblings
+     */
     QList<NavigationItemModel *> getSiblings();
 
+    /**
+     * @brief Append a child
+     * @param item Child item.
+     */
     void appendChild(NavigationItemModel* item);
+    /**
+     * @brief Remove all child items.
+     *
+     * Will delete children via deleteLater
+     */
     void clearChildren();
 
-    Q_INVOKABLE void onClicked();
+public slots:
+    /**
+     * @brief Defines behavior on clicking the current navigation item. Emits the clicked-signal.
+     */
+    void onClicked();
 
 private:
     QString mPath = QString("");
     QString mImageSource;
 
-    QList<NavigationItemModel*> mChildren = QList<NavigationItemModel*>();
+    QList<NavigationItemModel*> mChildren;
     NavigationItemModel* mParentItem;
 };
 

LenaPi/models/NavigationListModel.cpp

@@ -1,18 +1,13 @@
 #include "NavigationListModel.h"
-
 #include "NavigationItemModel.h"
 
-NavigationListModel::NavigationListModel(QObject* parent) : QObject(parent)
-{
-  /*nothing*/
-}
 
-QList<QObject *> NavigationListModel::getModelItems()
+ QList<QObject*> NavigationListModel::getModelItems()
 {
     return mItems;
 }
 
-void NavigationListModel::setModelItems(QList<NavigationItemModel *> list)
+void NavigationListModel::setModelItems(const QList<NavigationItemModel*>& list)
 {
     mItems.clear();
     for(const auto& item : list){

LenaPi/models/NavigationListModel.h

@@ -5,20 +5,24 @@
 
 class NavigationItemModel;
 
+/**
+ * @brief Model containing navigation items and handling navigation.
+ * @todo Check whether we can use QAbstractListModel here!
+ */
 class NavigationListModel : public QObject
 {
     Q_OBJECT
-    Q_PROPERTY(QList<QObject*> pModelItems READ getModelItems NOTIFY modelItemsChanged)
+    Q_PROPERTY( QList<QObject*> pModelItems READ getModelItems NOTIFY modelItemsChanged)
     Q_PROPERTY(bool pIsBackVisible READ isBackVisible NOTIFY modelItemsChanged)
 
 signals:
     void modelItemsChanged();
 
 public:
-    NavigationListModel(QObject* parent = Q_NULLPTR);
+    explicit NavigationListModel(QObject* parent = nullptr) : QObject(parent) { /* nothing */ }
 
     QList<QObject*> getModelItems();
-    void setModelItems(QList<NavigationItemModel*> list);
+    void setModelItems(const QList<NavigationItemModel*>& list);
 
     bool isBackVisible();
 

LenaPi/models/UiStateModel.h

@@ -4,6 +4,12 @@
 #include <QObject>
 #include <QUrl>
 
+/**
+ * @brief Handles state of UI by providing the qml source.
+ *
+ * Provides the possibility to switch between different
+ * ui states such as music player or navigation.
+ */
 class UiStateModel : public QObject
 {
     Q_OBJECT
@@ -14,7 +20,7 @@ signals:
     void sourceChanged();
 
 public:
-    UiStateModel(QObject *parent = Q_NULLPTR);
+    explicit UiStateModel(QObject *parent = nullptr);
 
     QUrl getSource() const;