cosmos 3.8.3 → 3.9.1

data/lib/cosmos/gui/dialogs/calendar_dialog.rb

@@ -14,17 +14,16 @@
 require 'cosmos'
 
 module Cosmos
-
-  # CalendarDialog class
-  #
+  # Creates a dialog with a date and optional time selection
   class CalendarDialog < Qt::Dialog
-
-    # The selected time
+    # @return [Time] User entered time
     attr_reader :time
 
-    # Constructor
-    def initialize (parent, title, initial_time = nil, show_time = true)
-      # Call base class constructor
+    # @param parent [Qt::Widget] Parent of this dialog
+    # @param title [String] Dialog title
+    # @param initial_time [Time] Initial time to display
+    # @param show_time [Boolean] Whether to display the time selection
+    def initialize(parent, title, initial_time = nil, show_time = true)
       super(parent)
       setWindowTitle(title)
 
@@ -90,13 +89,12 @@ module Cosmos
       @layout.addLayout(@button_layout)
 
       setLayout(@layout)
-    end # def initialize
+    end
 
     protected
 
     # Handler for the OK button being pressed - builds the time object
     def handle_ok_button
-      # Get calendar selected day
       @date = @calendar.selectedDate
 
       # Reduce @time to time at midnight of day
@@ -130,7 +128,5 @@ module Cosmos
       @date = @calendar.selectedDate
       @year_month_day.setText(sprintf("%04u/%02u/%02u", @date.year, @date.month, @date.day))
     end
-
-  end # class CalendarDialog
-
-end # module Cosmos
+  end
+end

data/lib/cosmos/gui/dialogs/cmd_details_dialog.rb

@@ -15,8 +15,9 @@ require 'cosmos'
 require 'cosmos/gui/dialogs/details_dialog'
 
 module Cosmos
-
+  # Creates a dialog which shows the details of the given command.
   class CmdDetailsDialog < DetailsDialog
+    # (see DetailsDialog#initialize)
     def initialize(parent, target_name, packet_name, item_name)
       super(parent, target_name, packet_name, item_name)
 
@@ -45,8 +46,6 @@ module Cosmos
       rescue DRb::DRbConnError
         # Just do nothing
       end
-
     end
-  end # class CmdDetailsDialog
-
-end # module Cosmos
+  end
+end

data/lib/cosmos/gui/dialogs/cmd_tlm_raw_dialog.rb

@@ -15,19 +15,27 @@ require 'cosmos'
 require 'cosmos/gui/qt'
 
 module Cosmos
-
+  # Creates a dialog showing a packet formatted as a binary hex dump
   class RawDialog < Qt::Dialog
     slots 'packet_update_timeout()'
 
+    # Constant to indicate a command packet dump
     CMD_TYPE = 'cmd'
+    # Constant to indicate a telemetry packet dump
     TLM_TYPE = 'tlm'
+    # Dialog update period
     PACKET_UPDATE_PERIOD_MS = 1000
-    HEADER1 = "Address   Data                                             Ascii\n"
-    HEADER2 = "---------------------------------------------------------------------------\n"
-    HEADER  = HEADER1 + HEADER2
+    # Header string to display over the dump
+    HEADER = "Address   Data                                             Ascii\n"\
+             "---------------------------------------------------------------------------\n"
 
+    # @return [Qt::Font] Font to display the dialog dump (should be monospaced)
     @@font = nil
 
+    # @param parent [Qt::Dialog] Parent for the dialog
+    # @param type [String] Dialog type which must be 'cmd' or 'tlm'
+    # @param target_name [String] Name of the target
+    # @param packet_name [String] Name of the packet
     def initialize(parent, type, target_name, packet_name)
       super(parent, Qt::WindowTitleHint | Qt::WindowSystemMenuHint)
       raise "RawDialog: Undefined type:#{type}" if type != CMD_TYPE and type != TLM_TYPE
@@ -97,6 +105,7 @@ module Cosmos
       end
     end
 
+    # Callback to get the latest packet and update the dialog
     def packet_update_timeout
       if (@type == CMD_TYPE)
         packet = System.commands.packet(@target_name, @packet_name)
@@ -115,35 +124,40 @@ module Cosmos
 
     def reject
       super()
-      if @timer
-        @timer.stop
-        @timer.dispose
-        @timer = nil
-      end
+      stop_timer if @timer
       self.dispose
     end
 
     def closeEvent(event)
       super(event)
-      if @timer
-        @timer.stop
-        @timer.dispose
-        @timer = nil
-      end
+      stop_timer if @timer
       self.dispose
     end
-  end # class RawDialog
 
+    def stop_timer
+      @timer.stop
+      @timer.dispose
+      @timer = nil
+    end
+  end
+
+  # Creates a dialog which displays a command packet as a hex dump
   class CmdRawDialog < RawDialog
+    # @param parent (see RawDialog#initialize)
+    # @param target_name (see RawDialog#initialize)
+    # @param packet_name (see RawDialog#initialize)
     def initialize(parent, target_name, packet_name)
       super(parent, RawDialog::CMD_TYPE, target_name, packet_name)
     end
   end
 
+  # Creates a dialog which displays a telemetry packet as a hex dump
   class TlmRawDialog < RawDialog
+    # @param parent (see RawDialog#initialize)
+    # @param target_name (see RawDialog#initialize)
+    # @param packet_name (see RawDialog#initialize)
     def initialize(parent, target_name, packet_name)
       super(parent, RawDialog::TLM_TYPE, target_name, packet_name)
     end
   end
-
-end # module Cosmos
+end

data/lib/cosmos/gui/dialogs/details_dialog.rb

@@ -13,11 +13,17 @@ require 'cosmos/gui/qt'
 require 'cosmos/script'
 
 module Cosmos
-
+  # Creates a dialog showing the details about a given command or telemetry
+  # item. This class is a base class and should not be instantiated. Use
+  # CmdDetailsDialog or TlmDetailsDialog.
   class DetailsDialog < Qt::Dialog
-
+    # @return [Array<DetailsDialog>] Instances of the details dialog
     @@instances = []
 
+    # @param parent [Qt::Dialog] Parent for the dialog
+    # @param target_name [String] Name of the target
+    # @param packet_name [String] Name of the packet
+    # @param item_name [String] Name of the item
     def initialize(parent, target_name, packet_name, item_name)
       super(parent, Qt::WindowTitleHint | Qt::WindowSystemMenuHint)
 
@@ -30,6 +36,9 @@ module Cosmos
       @@instances << self
     end
 
+    protected
+
+    # Creates and populates the layout for the dialog
     def build_details_layout(item, cmd_tlm)
       details_layout = Qt::FormLayout.new
       details_layout.addRow("Bit Offset:", Qt::Label.new(tr("#{show_nil(item.bit_offset)}")))
@@ -51,34 +60,8 @@ module Cosmos
       details_layout.addRow("Units Full:", Qt::Label.new(tr("#{show_nil(item.units_full)}")))
       details_layout.addRow("Units Abbreviation:", Qt::Label.new(tr("#{show_nil(item.units)}")))
       details_layout.addRow("Endianness:", Qt::Label.new(tr("#{show_endianness(item.endianness)}")))
-      state_colors = item.state_colors
       if item.states
-        states_details = Qt::GroupBox.new(tr("States"))
-        scroll_layout = Qt::VBoxLayout.new
-        states_details.setLayout(scroll_layout)
-        scroll_area = Qt::ScrollArea.new
-        scroll_area.setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff)
-        scroll_layout.addWidget(scroll_area)
-        scroll_widget = Qt::Widget.new
-        scroll_area.setWidget(scroll_widget)
-        states_layout = Qt::FormLayout.new
-        scroll_widget.setLayout(states_layout)
-        item.states.sort {|a, b| a[1] <=> b[1]}.each do |state_name, state_value|
-          if state_colors
-            states_layout.addRow(tr("#{state_name}:"), Qt::Label.new(tr("#{state_value} #{state_colors[state_name]}")))
-          else
-            states_layout.addRow(tr("#{state_name}:"), Qt::Label.new(tr("#{state_value}")))
-          end
-        end
-        # Figure out the how big the states layout wants to be and set the
-        # scroll area to this height if possible. Otherwise limit it to 200px.
-        if states_layout.minimumSize.height > 200
-          scroll_area.setMinimumHeight(200)
-        else
-          scroll_area.setMinimumHeight(states_layout.minimumSize.height + 5)
-        end
-        scroll_widget.adjustSize
-        details_layout.addRow(states_details)
+        details_layout.addRow(build_states_details(item))
       else
         details_layout.addRow("States:", Qt::Label.new(tr("None")))
       end
@@ -87,23 +70,11 @@ module Cosmos
       else
         limits = item.limits.values
         if limits
-          limits_details = Qt::GroupBox.new(tr("Limits"))
-          @limits_layout = Qt::FormLayout.new
-          limits.each do |limits_set_name, limits_settings|
-            if limits_settings[4] and limits_settings[5]
-              label = Qt::Label.new("RL/#{limits_settings[0]} YL/#{limits_settings[1]} YH/#{limits_settings[2]} RH/#{limits_settings[3]} GL/#{limits_settings[4]} GH/#{limits_settings[5]}")
-            else
-              label = Qt::Label.new("RL/#{limits_settings[0]} YL/#{limits_settings[1]} YH/#{limits_settings[2]} RH/#{limits_settings[3]}")
-            end
-            @limits_labels[limits_set_name] = label
-            @limits_layout.addRow(tr("#{limits_set_name}:"), label)
-          end
-          limits_details.setLayout(@limits_layout)
-          details_layout.addRow(limits_details)
+          details_layout.addRow(build_limits_details(limits))
         else
           details_layout.addRow(tr("Limits:"), Qt::Label.new("None"))
         end
-        if limits || state_colors
+        if limits || item.state_colors
           details_layout.addRow(tr("Limits Checking Enabled:"), Qt::Label.new(tr("#{show_nil(item.limits.enabled)}")))
         end
         if limits
@@ -121,6 +92,53 @@ module Cosmos
       details_layout
     end
 
+    # Create the states details layout
+    def build_states_details(item)
+      states_details = Qt::GroupBox.new(tr("States"))
+      scroll_layout = Qt::VBoxLayout.new
+      states_details.setLayout(scroll_layout)
+      scroll_area = Qt::ScrollArea.new
+      scroll_area.setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff)
+      scroll_layout.addWidget(scroll_area)
+      scroll_widget = Qt::Widget.new
+      scroll_area.setWidget(scroll_widget)
+      states_layout = Qt::FormLayout.new
+      scroll_widget.setLayout(states_layout)
+      item.states.sort {|a, b| a[1] <=> b[1]}.each do |state_name, state_value|
+        if item.state_colors
+          states_layout.addRow(tr("#{state_name}:"), Qt::Label.new(tr("#{state_value} #{item.state_colors[state_name]}")))
+        else
+          states_layout.addRow(tr("#{state_name}:"), Qt::Label.new(tr("#{state_value}")))
+        end
+      end
+      # Figure out the how big the states layout wants to be and set the
+      # scroll area to this height if possible. Otherwise limit it to 200px.
+      if states_layout.minimumSize.height > 200
+        scroll_area.setMinimumHeight(200)
+      else
+        scroll_area.setMinimumHeight(states_layout.minimumSize.height + 5)
+      end
+      scroll_widget.adjustSize
+      states_details
+    end
+
+    # Create the limits details layout
+    def build_limits_details(limits)
+      limits_details = Qt::GroupBox.new(tr("Limits"))
+      @limits_layout = Qt::FormLayout.new
+      limits.each do |limits_set_name, limits_settings|
+        if limits_settings[4] and limits_settings[5]
+          label = Qt::Label.new("RL/#{limits_settings[0]} YL/#{limits_settings[1]} YH/#{limits_settings[2]} RH/#{limits_settings[3]} GL/#{limits_settings[4]} GH/#{limits_settings[5]}")
+        else
+          label = Qt::Label.new("RL/#{limits_settings[0]} YL/#{limits_settings[1]} YH/#{limits_settings[2]} RH/#{limits_settings[3]}")
+        end
+        @limits_labels[limits_set_name] = label
+        @limits_layout.addRow(tr("#{limits_set_name}:"), label)
+      end
+      limits_details.setLayout(@limits_layout)
+      limits_details
+    end
+
     def show_nil(object, show_as = 'nil')
       if object.nil?
         return show_as
@@ -168,7 +186,5 @@ module Cosmos
       @@instances.delete(self)
       self.dispose
     end
-
-  end # class DetailsDialog
-
-end # module Cosmos
+  end
+end

data/lib/cosmos/gui/dialogs/exception_dialog.rb

@@ -15,83 +15,92 @@ require 'cosmos'
 require 'cosmos/gui/qt'
 
 module Cosmos
-
+  # Creates a dialog to display a COSMOS exception to the user. The dialog can
+  # close the application and log the exception. This is the primary dialog to
+  # display when something goes unexpectedly wrong.
   class ExceptionDialog
+    # @return [Mutex] Mutex to make this dialog single threaded
     @@mutex = Mutex.new
 
+    # @param parent [Qt::Dialog] Parent of this dialog
+    # @param exception [Exception] Ruby Exception to display details about
+    # @param title [String] Title of the dialog
+    # @param exit_afterwards [Boolean] Whether to completely exit the
+    #   application after displaying the dialog. Useful for fatal exceptions.
+    # @param log_exception [Boolean] Whether to create an exception log file
+    # @param log_file [String] Name of the log file to create
     def initialize(parent, exception, title = 'COSMOS Exception', exit_afterwards = true, log_exception = true, log_file = nil)
-      if @@mutex.try_lock
-        unless exception.class == SystemExit or exception.class == Interrupt
-          # ConfigParser::Errors are configuration user errors. We don't want to clutter
-          # up list of real exceptions with user configuration errors.
-          # Same goes for FatalErrors
-          unless exception.class == ConfigParser::Error || exception.class == FatalError
-            log_file = Cosmos.write_exception_file(exception) if log_exception
-          end
+      return unless @@mutex.try_lock
 
-          if Qt::CoreApplication.instance
-            msg = Qt::MessageBox.new(parent)
-            msg.setWindowTitle(title)
-            msg.setTextFormat(Qt::RichText)
-            msg.setIcon(Qt::MessageBox::Critical)
-            case exception
-            # ConfigParser::Errors are a special case generated with a known format
-            # by the ConfigParser
-            when ConfigParser::Error
-              # Substitute the html tags '<' and '>' and then replace newlines with html breaks
-              usage = exception.usage.gsub("<","&#060;").gsub(">","&#062;").gsub("\n","<br/>")
-              message = exception.message.gsub("<","&#060;").gsub(">","&#062;").gsub("\n","<br/>")
-              line = exception.keyword + ' ' + exception.parameters.join(' ').gsub("<","&#060;").gsub(">","&#062;").gsub("\n","<br/>")
-              text = "Error in #{exception.filename}<br/><br/>Line #{exception.line_number}: #{line}<br/><br/>#{message}<br/><br/>#{usage}"
-              unless exception.url.nil?
-                text << "<br/><br/>For more information see <a href='#{exception.url}'>#{exception.url}</a>."
-              end
-            # FatalErrors are errors explicitly raised when a known fatal issue
-            # occurs. Since it is a known issue we don't put up the full error
-            # dialog.
-            when FatalError
-              text = "Error: #{exception.message.gsub("\n","<br/>")}"
-            else
-              file_contents = ""
-              # First read the log_file we wrote out to the logs directory
-              # Change newlines to %0A for Outlook and remove all quotes to avoid breaking the link
-              begin
-                message = exception.message.gsub("\n","<br/>")
-                file_contents = File.read(log_file).gsub("\n","%0A").gsub("'","").gsub("\"","") if log_file
-              rescue
-              end
-              text = "The following error occurred:<br/>#{message}"
-              text << "<br/><br/>Please contact your local COSMOS expert.<br/><br/>This error has been logged:<br/>#{log_file}<br/><br/> <a href='mailto:rmelton@ball.com;jmthomas@ball.com?subject=COSMOS exception&body=#{file_contents}'>Click here</a> to email this log to the COSMOS developers." if log_file
+      unless exception.class == SystemExit || exception.class == Interrupt
+        # ConfigParser::Errors are configuration user errors. We don't want to clutter
+        # up list of real exceptions with user configuration errors.
+        # Same goes for FatalErrors
+        unless exception.class == ConfigParser::Error || exception.class == FatalError
+          log_file = Cosmos.write_exception_file(exception) if log_exception
+        end
+
+        if Qt::CoreApplication.instance
+          msg = Qt::MessageBox.new(parent)
+          msg.setWindowTitle(title)
+          msg.setTextFormat(Qt::RichText)
+          msg.setIcon(Qt::MessageBox::Critical)
+          case exception
+          # ConfigParser::Errors are a special case generated with a known format
+          # by the ConfigParser
+          when ConfigParser::Error
+            # Substitute the html tags '<' and '>' and then replace newlines with html breaks
+            usage = exception.usage.gsub("<","&#060;").gsub(">","&#062;").gsub("\n","<br/>")
+            message = exception.message.gsub("<","&#060;").gsub(">","&#062;").gsub("\n","<br/>")
+            line = exception.keyword + ' ' + exception.parameters.join(' ').gsub("<","&#060;").gsub(">","&#062;").gsub("\n","<br/>")
+            text = "Error in #{exception.filename}<br/><br/>Line #{exception.line_number}: #{line}<br/><br/>#{message}<br/><br/>#{usage}"
+            unless exception.url.nil?
+              text << "<br/><br/>For more information see <a href='#{exception.url}'>#{exception.url}</a>."
             end
-            text << "<br/><br/>NOTE!: The application will exit once you accept or dismiss this dialog!" if exit_afterwards
-            msg.setText(text)
-            if log_file
-              open_button = Qt::PushButton.new("Open Exception Log in Text Editor")
-              open_button.connect(SIGNAL('clicked()')) do
-                Cosmos.open_in_text_editor(log_file)
-                sleep(2)
-              end
-              msg.addButton(open_button, Qt::MessageBox::ResetRole)
+          # FatalErrors are errors explicitly raised when a known fatal issue
+          # occurs. Since it is a known issue we don't put up the full error
+          # dialog.
+          when FatalError
+            text = "Error: #{exception.message.gsub("\n","<br/>")}"
+          else
+            file_contents = ""
+            # First read the log_file we wrote out to the logs directory
+            # Change newlines to %0A for Outlook and remove all quotes to avoid breaking the link
+            begin
+              message = exception.message.gsub("\n","<br/>")
+              file_contents = File.read(log_file).gsub("\n","%0A").gsub("'","").gsub("\"","") if log_file
+            rescue
             end
-            close_button = Qt::PushButton.new("Close")
-            msg.addButton(close_button, Qt::MessageBox::ActionRole)
-            msg.raise
-            msg.exec
-            msg.dispose
-          end # if Qt::CoreApplication.instance
-        end #  unless exception.class == SystemExit or exception.class == Interrupt
-        @@mutex.unlock
-        if exit_afterwards
-          Qt::CoreApplication.instance.exit(1) if Qt::CoreApplication.instance
-          exit 1 # incase CoreApplication doesn't exit yet or didn't complete the exit
-        end
-      end # if @@mutex.try_lock
+            text = "The following error occurred:<br/>#{message}"
+            text << "<br/><br/>Please contact your local COSMOS expert.<br/><br/>This error has been logged:<br/>#{log_file}<br/><br/> <a href='mailto:rmelton@ball.com;jmthomas@ball.com?subject=COSMOS exception&body=#{file_contents}'>Click here</a> to email this log to the COSMOS developers." if log_file
+          end
+          text << "<br/><br/>NOTE!: The application will exit once you accept or dismiss this dialog!" if exit_afterwards
+          msg.setText(text)
+          if log_file
+            open_button = Qt::PushButton.new("Open Exception Log in Text Editor")
+            open_button.connect(SIGNAL('clicked()')) do
+              Cosmos.open_in_text_editor(log_file)
+              sleep(2)
+            end
+            msg.addButton(open_button, Qt::MessageBox::ResetRole)
+          end
+          close_button = Qt::PushButton.new("Close")
+          msg.addButton(close_button, Qt::MessageBox::ActionRole)
+          msg.raise
+          msg.exec
+          msg.dispose
+        end # if Qt::CoreApplication.instance
+      end #  unless exception.class == SystemExit or exception.class == Interrupt
+      @@mutex.unlock
+      if exit_afterwards
+        Qt::CoreApplication.instance.exit(1) if Qt::CoreApplication.instance
+        exit 1 # incase CoreApplication doesn't exit yet or didn't complete the exit
+      end
     end # def initialize
 
+    # @return [Boolean] Whether this dialog has already been instantiated
     def self.dialog_open?
       @@mutex.locked?
     end
-
-  end # class ExceptionDialog
-
-end # module Cosmos
+  end
+end