comment while learning UI

Author: Gin

SerialPrograms/Scripts/CodeTemplates/Program/GameName_ProgramName.h

@@ -16,7 +16,6 @@ namespace NintendoSwitch{
 namespace GameName{
 
 
-
 class ProgramName_Descriptor : public SingleSwitchProgramDescriptor{
 public:
     ProgramName_Descriptor();

SerialPrograms/Source/CommonFramework/Panels/PanelInstance.h

@@ -31,6 +31,8 @@ class PanelInstance{
     void save_settings() const;
 
 public:
+    // The implmentation is defined in "UI/PanelWidget.h" to avoid circular dependency
+    // Returns a UI/PanelWidget.h:PanelWidget
     virtual QWidget* make_widget(QWidget& parent, PanelHolder& holder);
 
 public:

SerialPrograms/Source/CommonFramework/Panels/PanelTools.h

@@ -17,7 +17,17 @@ class JsonValue;
 class PanelInstance;
 class PanelDescriptor;
 
-
+// Abstract base class of a panel holder.
+// It is named as the owner of all the panel instances.
+// A panel instance, CommonFramework/Panels/PanelInstance.h:PanelInstance holds
+// both the program panel UI and the implementation of the actual program logic.
+//
+// Currently the main window is the only class that implements PanelHolder.
+// The reference of this panel holder is passed to various UI objects so that
+// when they do sth they can call back to the main window. e.g. when the progra
+// start button is pressed by user, the button code needs to lock the program
+// list UI. This is achieved by letting the button code calls PanelHolder::on_busy()
+// which is implemented by the main window
 struct PanelHolder{
     //  Returns true if ready for new panel.
     virtual bool report_new_panel_intent(const PanelDescriptor& descriptor) = 0;
@@ -27,7 +37,9 @@ struct PanelHolder{
         std::unique_ptr<PanelInstance> panel
     ) = 0;
     virtual Logger& raw_logger() = 0;
+    // called when an automation program is running
     virtual void on_busy() = 0;
+    // called when no automation program is not running
     virtual void on_idle() = 0;
 };
 
@@ -52,16 +64,18 @@ struct PanelEntry{
 template <typename Descriptor, typename Instance>
 class PanelDescriptorWrapper : public Descriptor{
 public:
+    // Instance must be an inherited class of PanelInstance and its constructor must be
+    // Instance(const Descriptor&)
     virtual std::unique_ptr<PanelInstance> make_panel() const override{
-        return std::unique_ptr<PanelInstance>(new Instance(*this));
+        return std::make_unique<Instance>(*this);
     }
 };
 
 // Called by a program panel list factory to create a panel descriptor.
 // A panel descriptor holds various info (title, title color, etc.) about a program panel
 // and can also create the corresponding panel.
 //
-// template type `Descriptor` a derived class of CommonFramework/Panels/PanelDescriptor.h:PanelDescriptor
+// template type `Descriptor` is a derived class of CommonFramework/Panels/PanelDescriptor.h:PanelDescriptor
 // and `Instance` is the program panel UI instance, derived class of 
 // CommonFramework/Panels/PanelInstance.h:Panelnstance.
 //

SerialPrograms/Source/CommonFramework/Panels/UI/PanelWidget.h

@@ -14,6 +14,10 @@ namespace PokemonAutomation{
 
 class CollapsibleGroupBox;
 
+// A base class to define the UI widgets of a program panel.
+// A PanelInstance can call make_widget() to create it.
+// Its derived classes can call make_header() to create a collabspile program header
+// that shows program title, link to online documentation and others.
 class PanelWidget : public QWidget{
 public:
     PanelWidget(
@@ -23,6 +27,7 @@ class PanelWidget : public QWidget{
     );
     virtual ~PanelWidget() = default;
 
+    // return the panel instance
     PanelInstance& instance(){ return m_instance; }
 
 protected:

SerialPrograms/Source/CommonFramework/Windows/MainWindow.h

@@ -40,15 +40,22 @@ class MainWindow :
 
     void close_panel() noexcept;
 
+    // implements PanelHolder::report_new_panel_intent()
     virtual bool report_new_panel_intent(const PanelDescriptor& descriptor) override;
+    // implements PanelHolder::load_panel()
     virtual void load_panel(
         std::shared_ptr<const PanelDescriptor> descriptor,
         std::unique_ptr<PanelInstance> panel
     ) override;
+    // implements PanelHolder::raw_logger()
     virtual Logger& raw_logger() override{ return global_logger_raw(); }
 
 private:
+    // implements PanelHolder::on_busy()
+    // called when an automation program is running
     virtual void on_busy() override;
+    // implements PanelHolder::on_idle()
+    // called when no automation program is not running
     virtual void on_idle() override;
     virtual void on_config_value_changed(void* object) override;
     virtual void sleep_suppress_state_changed(SleepSuppress new_state) override;

SerialPrograms/Source/NintendoSwitch/Framework/NintendoSwitch_SwitchSystemOption.h

@@ -34,6 +34,9 @@ Color pick_color(
 );
 
 
+// options to control and monitor a Switch. It inlcudes
+// what micro-controller and what video source to use and
+// what video overlay display option to set.
 class SwitchSystemOption{
     static const std::string JSON_CONTROLLER;
     static const std::string JSON_CAMERA;

SerialPrograms/Source/NintendoSwitch/NintendoSwitch_SingleSwitchProgram.cpp

@@ -40,7 +40,7 @@ SingleSwitchProgramDescriptor::SingleSwitchProgramDescriptor(
     , m_allow_commands_while_running(allow_commands_while_running == AllowCommandsWhenRunning::ENABLE_COMMANDS)
 {}
 std::unique_ptr<PanelInstance> SingleSwitchProgramDescriptor::make_panel() const{
-    return std::unique_ptr<PanelInstance>(new SingleSwitchProgramOption(*this));
+    return std::make_unique<SingleSwitchProgramOption>(*this);
 }
 
 

SerialPrograms/Source/NintendoSwitch/Programs/NintendoSwitch_VirtualConsole.cpp

@@ -28,13 +28,13 @@ VirtualConsole_Descriptor::VirtualConsole_Descriptor()
 
 VirtualConsole::VirtualConsole(const VirtualConsole_Descriptor& descriptor)
     : PanelInstance(descriptor)
-    , m_switch({}, false)
+    , m_switch_control_option({}, false)
 {}
 void VirtualConsole::from_json(const JsonValue& json){
-    m_switch.load_json(json);
+    m_switch_control_option.load_json(json);
 }
 JsonValue VirtualConsole::to_json() const{
-    return m_switch.to_json();
+    return m_switch_control_option.to_json();
 }
 QWidget* VirtualConsole::make_widget(QWidget& parent, PanelHolder& holder){
     return VirtualConsole_Widget::make(parent, *this, holder);
@@ -52,15 +52,15 @@ VirtualConsole_Widget* VirtualConsole_Widget::make(
     return widget;
 }
 VirtualConsole_Widget::~VirtualConsole_Widget(){
-    delete m_switch;
+    delete m_switch_widget;
 }
 VirtualConsole_Widget::VirtualConsole_Widget(
     QWidget& parent,
     VirtualConsole& instance,
     PanelHolder& holder
 )
     : PanelWidget(parent, instance, holder)
-    , m_session(instance.m_switch, 0, 0)
+    , m_session(instance.m_switch_control_option, 0, 0)
 {}
 void VirtualConsole_Widget::construct(){
     QVBoxLayout* layout = new QVBoxLayout(this);
@@ -76,8 +76,8 @@ void VirtualConsole_Widget::construct(){
     QVBoxLayout* scroll_layout = new QVBoxLayout(scroll_inner);
     scroll_layout->setAlignment(Qt::AlignTop);
 
-    m_switch = new SwitchSystemWidget(*this, m_session, 0);
-    scroll_layout->addWidget(m_switch);
+    m_switch_widget = new SwitchSystemWidget(*this, m_session, 0);
+    scroll_layout->addWidget(m_switch_widget);
 }
 
 

SerialPrograms/Source/NintendoSwitch/Programs/NintendoSwitch_VirtualConsole.h

@@ -18,14 +18,21 @@ namespace NintendoSwitch{
 class SwitchSystemWidget;
 
 
-
+// Descriptor for the program "Virtual Console".
+// It defines basic info such as title name and color of the program on the program list panel.
+// It inherits abstract base class PanelDescriptor but is still an abstract class as it does
+// not define `make_panel()`, which functionality is simply to instantiate the PanelInstance, the
+// program panel.
+// Call CommonFramework/Panels/PanelTools.h:make_panel<VirtualConsole_Descriptor, VirtualConsole>()
+// to create a wrapper class that implements `make_panel()` to instantiate the descriptor.
 class VirtualConsole_Descriptor : public PanelDescriptor{
 public:
     VirtualConsole_Descriptor();
 };
 
 
-
+// The program panel of Virtual Console.
+// It calls make_widget() to create a VirtualConsole_Widget that holds the UI wideget.
 class VirtualConsole : public PanelInstance{
 public:
     VirtualConsole(const VirtualConsole_Descriptor& descriptor);
@@ -38,12 +45,13 @@ class VirtualConsole : public PanelInstance{
 
 private:
     friend class VirtualConsole_Widget;
-
-    SwitchSystemOption m_switch;
+    // switch control options like what micro-controller 
+    // and what video source to use
+    SwitchSystemOption m_switch_control_option;
 };
 
 
-
+// The UI of the prgoram Virtual Console
 class VirtualConsole_Widget : public PanelWidget{
 public:
     static VirtualConsole_Widget* make(
@@ -63,7 +71,7 @@ class VirtualConsole_Widget : public PanelWidget{
 
 private:
     SwitchSystemSession m_session;
-    SwitchSystemWidget* m_switch;
+    SwitchSystemWidget* m_switch_widget;
 };