Changeset 71373 in vbox for trunk/src/VBox

Timestamp:

Mar 19, 2018 12:36:23 PM (7 years ago)

Author:

vboxsync

Message:

FE/Qt: bugref:9049: Cleanup for UIModalWindowManager: Doxygen and coding-style.

Location:

trunk/src/VBox/Frontends/VirtualBox/src/globals

Files:

• UIModalWindowManager.cpp (modified) (11 diffs)
• UIModalWindowManager.h (modified) (4 diffs)

trunk/src/VBox/Frontends/VirtualBox/src/globals/UIModalWindowManager.cpp

@@ -5 +5 @@
 
 /*
- * Copyright (C) 2013-2017 Oracle Corporation
+ * Copyright (C) 2013-2018 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -27 +27 @@
 #  include "UINetworkManager.h"
 #  include "UINetworkManagerDialog.h"
-# endif /* VBOX_GUI_WITH_NETWORK_MANAGER */
+# endif
 # include "UIProgressDialog.h"
 # include "UISelectorWindow.h"
@@ -38 +38 @@
 
 /* static */
-UIModalWindowManager* UIModalWindowManager::m_spInstance = 0;
-UIModalWindowManager* UIModalWindowManager::instance() { return m_spInstance; }
+UIModalWindowManager *UIModalWindowManager::s_pInstance = 0;
+UIModalWindowManager *UIModalWindowManager::instance() { return s_pInstance; }
 
 /* static */
@@ -45 +45 @@
 {
     /* Make sure instance is NOT created yet: */
-    if (m_spInstance)
+    if (s_pInstance)
     {
         AssertMsgFailed(("UIModalWindowManager instance is already created!"));
@@ -59 +59 @@
 {
     /* Make sure instance is NOT destroyed yet: */
-    if (!m_spInstance)
+    if (!s_pInstance)
     {
         AssertMsgFailed(("UIModalWindowManager instance is already destroyed!"));
@@ -66 +66 @@
 
     /* Destroy instance: */
-    delete m_spInstance;
+    delete s_pInstance;
 }
 
@@ -72 +72 @@
 {
     /* Assign instance: */
-    m_spInstance = this;
+    s_pInstance = this;
 }
 
@@ -78 +78 @@
 {
     /* Unassign instance: */
-    m_spInstance = 0;
-}
-
-QWidget* UIModalWindowManager::mainWindowShown() const
+    s_pInstance = 0;
+}
+
+QWidget *UIModalWindowManager::mainWindowShown() const
 {
     /* It may happen that this method is called before VBoxGlobal initialization
@@ -112 +112 @@
 
 #ifdef VBOX_GUI_WITH_NETWORK_MANAGER
-QWidget* UIModalWindowManager::networkManagerOrMainWindowShown() const
-{
-    /* It may happen that this method is called before network-manager initialization
-     * or when the network-manager is hidden, return main application window in this case: */
+QWidget *UIModalWindowManager::networkManagerOrMainWindowShown() const
+{
+    /* Return main application window before network-manager initialization: */
     return gNetworkManager && gNetworkManager->window()->isVisible() ? gNetworkManager->window() : mainWindowShown();
 }
 #endif /* VBOX_GUI_WITH_NETWORK_MANAGER */
 
-QWidget* UIModalWindowManager::realParentWindow(QWidget *pWidget)
+QWidget *UIModalWindowManager::realParentWindow(QWidget *pWidget)
 {
     /* Null if widget pointer is null: */
@@ -163 +162 @@
 }
 
-void UIModalWindowManager::registerNewParent(QWidget *pWindow, QWidget *pParentWindow /* = 0*/)
+void UIModalWindowManager::registerNewParent(QWidget *pWindow, QWidget *pParentWindow /* = 0 */)
 {
     /* Make sure passed-widget-pointer is not null: */
@@ -274 +273 @@
 }
 
-bool UIModalWindowManager::contains(QWidget *pParentWindow, bool fAsTheTopOfStack /* = false*/)
+bool UIModalWindowManager::contains(QWidget *pParentWindow, bool fAsTheTopOfStack /* = false */)
 {
     /* False if passed-parent-widget pointer is null: */

trunk/src/VBox/Frontends/VirtualBox/src/globals/UIModalWindowManager.h

@@ -5 +5 @@
 
 /*
- * Copyright (C) 2013-2017 Oracle Corporation
+ * Copyright (C) 2013-2018 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -16 +16 @@
  */
 
-#ifndef __UIModalWindowManager_h__
-#define __UIModalWindowManager_h__
+#ifndef ___UIModalWindowManager_h___
+#define ___UIModalWindowManager_h___
 
 /* Qt includes: */
@@ -24 +24 @@
 #include <QList>
 
-/* Object which contains stack(s) of guarded-pointer(s)
- * to the current top-level modal-window(s)
- * which could be used to determine top-level modal-dialog(s): */
+/** QObject subclass which contains a stack(s) of guarded-pointer(s) to the current top-level
+  * modal-window(s) which could be used to determine parents for new top-level modal-dialog(s). */
 class UIModalWindowManager : public QObject
 {
@@ -38 +37 @@
 public:
 
-    /* Static API: Create/destroy stuff: */
+    /** Creates the static singleton instance. */
     static void create();
+    /** Destroys the static singleton instance. */
     static void destroy();
 
-    /* API: Access stuff: */
-    QWidget* realParentWindow(QWidget *pPossibleParentWidget);
+    /** Returns actual top-level parent window for a passed @a pPossibleParentWidget. */
+    QWidget *realParentWindow(QWidget *pPossibleParentWidget);
+    /** Returns whether passed @a pWindow is in the modal window stack. */
     bool isWindowInTheModalWindowStack(QWidget *pWindow);
+    /** Returns whether passed @a pWindow is on the top of the modal window stack. */
     bool isWindowOnTheTopOfTheModalWindowStack(QWidget *pWindow);
 
-    /* API: Register stuff: */
+    /** Registers new parent @a pWindow above the passed @a pParentWindow or as separate stack. */
     void registerNewParent(QWidget *pWindow, QWidget *pParentWindow = 0);
 
-    /* API: Main application window stuff: */
-    QWidget* mainWindowShown() const;
+    /** Returns main application window. */
+    QWidget *mainWindowShown() const;
 #ifdef VBOX_GUI_WITH_NETWORK_MANAGER
+    /** Returns network manager or main window shown. */
     QWidget* networkManagerOrMainWindowShown() const;
-#endif /* VBOX_GUI_WITH_NETWORK_MANAGER */
+#endif
 
 private slots:
 
-    /* Handler: Stack cleanup stuff: */
+    /** Removes window with base-class @a pObject pointer from the stack. */
     void sltRemoveFromStack(QObject *pObject);
 
 private:
 
-    /* Constructor/destructor: */
+    /** Constructs Modal Window Manager instance. */
     UIModalWindowManager();
+    /** Destructs Modal Window Manager instance. */
     ~UIModalWindowManager();
 
-    /* Helper: Stack stuff: */
+    /** Returns whether stack contains @a pParentWindow at all or @a fAsTheTopOfStack. */
     bool contains(QWidget *pParentWindow, bool fAsTheTopOfStack = false);
 
-    /* Static helper: Access stuff: */
+    /** WORKAROUND: Preprocess (show) real parent for a passed @a pParent. */
     static void preprocessRealParent(QWidget *pParent);
 
-    /* Variables: */
+    /** Holds the list of the top-level window stacks. */
     QList<QList<QWidget*> > m_windows;
 
-    /* Static API: Instance stuff: */
-    static UIModalWindowManager* m_spInstance;
-    static UIModalWindowManager* instance();
-    friend UIModalWindowManager& windowManager();
+    /** Holds the static singleton instance. */
+    static UIModalWindowManager *s_pInstance;
+    /** Returns the static singleton instance. */
+    static UIModalWindowManager *instance();
+    /** Allows friend-access for static singleton instance. */
+    friend UIModalWindowManager &windowManager();
 };
 
-/* Shortcut to the static UIModalWindowManager::instance() method: */
-inline UIModalWindowManager& windowManager() { return *(UIModalWindowManager::instance()); }
+/** Singleton Modal Window Manager 'official' name. */
+inline UIModalWindowManager &windowManager() { return *(UIModalWindowManager::instance()); }
 
-#endif /* !__UIModalWindowManager_h__ */
+#endif /* !___UIModalWindowManager_h___ */
+