cosmos 3.8.3 → 3.9.1

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

@@ -16,10 +16,13 @@ require 'cosmos/gui/qt'
 require 'cosmos/gui/dialogs/exception_dialog'
 
 module Cosmos
-
   # Displays a list of exceptions in a dialog box. Clicking on any of the
   # exceptions creates a new ExceptionDialog which shows the details.
   class ExceptionListDialog < Qt::Dialog
+    # @param message [String] Text to display in the dialog
+    # @param exception_list [Array<Exception>] Array of exceptions to display
+    # @param title [String] Dialog title
+    # @param parent [Qt::Widget] Parent for this dialog
     def initialize(message, exception_list, title = 'COSMOS Exception List', parent = Qt::CoreApplication.instance.activeWindow)
       super(parent)
       self.window_title = title
@@ -53,7 +56,5 @@ module Cosmos
       exec()
       dispose()
     end
-  end # class ExceptionListDialog
-
-end # module Cosmos
-
+  end
+end

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

@@ -8,21 +8,18 @@
 # as published by the Free Software Foundation; version 3 with
 # attribution addendums as found in the LICENSE.txt
 
-# This file contains the implementation of the LegalDialog class.   This class
-# is used to display a legal dialog box
-
 require 'cosmos'
 require 'cosmos/gui/qt'
 require 'open3'
 
 module Cosmos
-
+  # Creates a dialog displaying the COSMOS copyright information. Also
+  # calculates CRC checks across the entire project to determine if any of the
+  # COSMOS core files have been modified. This ensures the COSMOS system has
+  # not been modified since the last release.
   class LegalDialog < Qt::Dialog
-
     def initialize
       super() # MUST BE FIRST
-
-      # Set Default Icon
       Cosmos.load_cosmos_icon
 
       self.window_title = 'Legal Agreement'
@@ -37,20 +34,27 @@ module Cosmos
       label.setFrameStyle(Qt::Frame::Box)
       layout.addWidget(label)
 
+      version = Qt::Label.new("COSMOS Version: " + COSMOS_VERSION)
+      version.setFont(Cosmos.getFont("Arial", 14))
+      version_layout = Qt::HBoxLayout.new
+      version_layout.addWidget(version, 0, Qt::AlignCenter)
+      layout.addLayout(version_layout)
+
       legal_text = ''
       legal_text_filename = File.join(::Cosmos::USERPATH, 'config', 'data', 'legal.txt')
       legal_text_filename = File.join(::Cosmos::PATH, 'data', 'legal.txt') unless File.exist?(legal_text_filename)
-      File.open(legal_text_filename, "r") {|file| legal_text << file.read}
+      legal_text << File.read(legal_text_filename)
+      legal_text.strip!
       legal_text.gsub!("\r", '') unless Kernel.is_windows?
 
-      text_edit = Qt::TextEdit.new
-      text_edit.text = legal_text
-      text_edit.setReadOnly(true)
-      text_edit.setFrameStyle(Qt::Frame::Box)
-      layout.addWidget(text_edit)
+      legal_label = Qt::Label.new(legal_text)
+      legal_label.setWordWrap(true)
+      legal_label.setFrameStyle(Qt::Frame::Box)
+      legal_label.setStyleSheet("QLabel { background-color : white; padding: 5px; }");
+      layout.addWidget(legal_label)
 
       @text_crc = Qt::TextEdit.new
-      @text_crc.setFixedHeight(100)
+      @text_crc.setMinimumHeight(100)
       @text_crc.setReadOnly(true)
       @text_crc.setFrameStyle(Qt::Frame::Box)
       layout.addWidget(@text_crc)
@@ -81,16 +85,21 @@ module Cosmos
       hlayout.addWidget(update_crc_button, 0, Qt::AlignCenter) if update_crc_button
       hlayout.addWidget(cancel_button, 0, Qt::AlignRight)
       layout.addLayout(hlayout)
-  
+
       self.show()
       self.raise()
       result = exec()
       dispose()
       exit if result != Qt::Dialog::Accepted
-    end # initialize
+    end
 
+    # Opens all the files listed in <Cosmos::PATH>/data/crc.txt and calculates their CRCs
+    # against what is listed in the file to detect any modifications. Also
+    # opens all files listed in <Cosmos::USERPATH/config/data/crc.txt to verify
+    # the user defined COSMOS configuration files.
+    # @return [String] Either a success message or warning about all files
+    #   which did not match their expected CRCs.
     def check_all_crcs
-      # Check each file in crc.txt
       result_text = ''
       missing_text = ''
       core_file_count, core_error_count, _, _ = check_crcs(::Cosmos::PATH, File.join(::Cosmos::PATH,'data','crc.txt'), result_text, missing_text, 'CORE')
@@ -128,6 +137,12 @@ module Cosmos
       return project_error_count
     end
 
+    # @param base_path [String] Path to prepend to all the files in crc.txt
+    # @param filename [String] Full path to the crc.txt file
+    # @param result_text [String] String to append results of CRC checks
+    # @param missing_text [String] String to append missing files
+    # @param file_type [String] Whether the COSMOS core or project files. Must
+    #   be 'CORE' or 'PROJECT'.
     def check_crcs(base_path, filename, result_text, missing_text, file_type)
       file_count = 0
       error_count = 0
@@ -162,8 +177,6 @@ module Cosmos
         end
       end
       return file_count, error_count, missing_count, official
-    end # check_crcs
-
+    end
   end
-
-end # module Cosmos
+end

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

@@ -16,8 +16,24 @@ require 'cosmos/gui/qt'
 require 'cosmos/gui/widgets/packet_log_frame'
 
 module Cosmos
-
+  # Creates a dialog to allow a user to browse for a COSMOS log and select the
+  # time period to process.
   class PacketLogDialog < Qt::Dialog
+    extend Forwardable
+    def_delegators :@packet_log_frame, :filenames, :time_start, :time_start=,\
+      :time_end, :time_end=, :packet_log_reader
+
+    # @param parent (see PacketLogFrame#initialize)
+    # @param title [String] Dialog title
+    # @param log_directory (see PacketLogFrame#initialize)
+    # @param packet_log_reader (see PacketLogFrame#initialize)
+    # @param initial_filenames (see PacketLogFrame#initialize)
+    # @param initial_output_filename (see PacketLogFrame#initialize)
+    # @param show_output_filename (see PacketLogFrame#initialize)
+    # @param show_time (see PacketLogFrame#initialize)
+    # @param show_log_reader (see PacketLogFrame#initialize)
+    # @param input_filename_filter (see PacketLogFrame#initialize)
+    # @param output_filename_filter (see PacketLogFrame#initialize)
     def initialize(parent,
                    title,
                    log_directory,
@@ -29,13 +45,10 @@ module Cosmos
                    show_log_reader = true,
                    input_filename_filter = Cosmos::BIN_FILE_PATTERN,
                    output_filename_filter = Cosmos::BIN_FILE_PATTERN)
-      # Call base class constructor
       super(parent)
       setWindowTitle(title)
 
       @layout = Qt::VBoxLayout.new
-
-      # Create log frame
       @packet_log_frame = PacketLogFrame.new(self,
                                              log_directory,
                                              packet_log_reader,
@@ -66,41 +79,6 @@ module Cosmos
 
       @layout.addLayout(@button_layout)
       setLayout(@layout)
-    end # def initialize
-
-    # Returns the chosen filenames
-    def filenames
-      @packet_log_frame.filenames
-    end
-
-    # Return the output filename
-    def output_filename
-      @packet_log_frame.output_filename
-    end
-
-    # Return Start time of packets to process
-    def time_start
-      @packet_log_frame.time_start
-    end
-
-    # Set the start time
-    def time_start=(new_time_start)
-      @packet_log_frame.time_start = new_time_start
-    end
-
-    # Return End time of packets to process
-    def time_end
-      @packet_log_frame.time_end
-    end
-
-    # Set the end time
-    def time_end=(new_time_end)
-      @packet_log_frame.time_end = new_time_end
-    end
-
-    # Return Log reader to use
-    def packet_log_reader
-      @packet_log_frame.packet_log_reader
     end
 
     protected
@@ -112,7 +90,5 @@ module Cosmos
         @ok_button.setEnabled(true)
       end
     end
-
-  end # class PacketLogDialog
-
-end # module Cosmos
+  end
+end

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

@@ -15,41 +15,45 @@ require 'cosmos/gui/qt'
 require 'cosmos/gui/dialogs/exception_dialog'
 
 module Cosmos
-
-  # ProgressDialog class
-  #
-  # The QT GUI model is to use slots and signals to connect GUI elements together.
-  # This is especially important with multithreaded applications because only the main thread
-  # can update the GUI and other attempts will cause crashes.
-  #
-  # It seems like we should be able to do something like the following:
-  #   progress_dialog = ProgressDialog.new(self, 'Progress')
-  #   thread = MyRubyThreadWorker.new
-  #   connect(thread, SIGNAL('finished(int)'), progress_dialog, SLOT('done(int)'), Qt::QueuedConnection)
-  #   thread.start
-  #   progress_dialog.exec
-  #
-  # This is creating a thread (but not starting the thread) and then connecting the thread
-  # classes 'finished(int)' signal to the progress_dialog classes 'done(int)' signal.
-  # It then starts the thread and calls exec on the dialog which makes it a modal dialog
-  # that starts its internal QEventLoop going. This allows the GUI to remain updating
-  # (so we can click cancel) while the thread runs. Then when the thread finished it should emit
-  # its 'finished(int)' signal which closes the dialog.
-  #
-  # This all SHOULD work but it tends to randomly crash on Ruby 1.8.6.
-  # HOWEVER, it appears to work well on 1.9.1. We should consider going to this model
-  # in COSMOS 2.0 as it avoids the hacky
-
+  # Dialog which shows a progress bar. Optionally can display two progress
+  # bars: one for overall progress and one for a sub-task. Can also optionally
+  # display informational text.
   class ProgressDialog < Qt::Dialog
+    # @return [#call] Called when the dialog is canceled. Passed the current
+    #   instance of the ProgressDialog
     attr_accessor :cancel_callback
+    # @return [Thread] Ruby thread associated with this dialog. If specified,
+    #   it will automatically be killed if the dialog is canceled.
     attr_accessor :thread
+    # Accessor to set the complete flag
     attr_writer :complete
 
     slots 'append_text(const QString&)'
     slots 'set_step_progress(int)'
     slots 'set_overall_progress(int)'
 
-    def initialize(parent, title, width = 500, height = 300, show_overall = true, show_step = true, show_text = true, show_done = true, show_cancel = true)
+    # @param parent [Qt::Widget] Parent of this dialog
+    # @param title [String] Dialog title
+    # @param width [Integer] Dialog width
+    # @param height [Integer] Dialog height
+    # @param show_overall [Boolean] Whether to show the overall progress bar
+    # @param show_step [Boolean] Whether to show the individual step progress
+    #   bar
+    # @param show_text [Boolean] Whether to show informational text along with
+    #   the progress bar
+    # @param show_done [Boolean] Whether to show a "Done" button which closes
+    #   the dialog once the progress is complete
+    # @param show_cancel [Boolean] Whether to show a "Cancel" button which
+    #   cancels and closes the dialog
+    def initialize(parent,
+                   title,
+                   width = 500,
+                   height = 300,
+                   show_overall = true,
+                   show_step = true,
+                   show_text = true,
+                   show_done = true,
+                   show_cancel = true)
       if show_cancel
         super(parent)
       else
@@ -129,24 +133,29 @@ module Cosmos
       @step_progress = 0
     end
 
+    # @return [Boolean] Whether this dialog was canceled
     def self.canceled?
       @@canceled
     end
 
+    # @return [Boolean] Whether this dialog was canceled
     def canceled?
       @@canceled
     end
 
+    # @return [Boolean] Whether this dialog successfully completed
     def complete?
-      return @complete
+      @complete
     end
 
+    # Enable the cancel button if it was specified
     def enable_cancel_button
       Qt.execute_in_main_thread(true) do
         @cancel_button.setEnabled(true) if @cancel_button
       end
     end
 
+    # Set complete to true and close the dialog
     def close_done
       Qt.execute_in_main_thread(true) do
         @complete = true
@@ -154,6 +163,8 @@ module Cosmos
       end
     end
 
+    # Call the cancel_callback if given to determine how to proceed. Set
+    # canceled to true and kill any associated threads.
     def close_cancel
       Qt.execute_in_main_thread(true) do
         kill_thread = true
@@ -174,25 +185,30 @@ module Cosmos
       end
     end
 
+    # Empty method to remove warning
+    # @comment TODO: What warning? How does this manifest?
     def graceful_kill
-      # Do nothing - just to remove warning
     end
 
+    # @param font [Font] Font to apply on the progress text
     def set_text_font(font)
       @progress_text.setFont(font)
     end
 
-    def append_text(string)
+    # @param text [String] Text to append to the progress text
+    def append_text(text)
       unless @complete
         Qt.execute_in_main_thread(false) do
           if @progress_text
-            @progress_text.appendPlainText(string)
+            @progress_text.appendPlainText(text)
             @progress_text.ensureCursorVisible
           end
         end
       end
     end
 
+    # Mark the dialog complete by enabling the Done and Cancel button if they
+    # were specified. This method does NOT close the dialog automatically.
     def complete
       Qt.execute_in_main_thread(true) do
         @done_button.setEnabled(true) if @done_button
@@ -200,9 +216,12 @@ module Cosmos
       end
     end
 
-    def set_step_progress (value)
+    # @comment TODO: Rename to step_progress=
+    # @param value [Float] Fraction from 0 to 1 of the current step that is
+    #   complete.
+    def set_step_progress(value)
       progress_int = (value * 100).to_i
-      if !@complete and @step_progress != progress_int
+      if !@complete && @step_progress != progress_int
         @step_progress = progress_int
         Qt.execute_in_main_thread(false) do
           @step_bar.setValue(progress_int) if @step_bar
@@ -210,9 +229,12 @@ module Cosmos
       end
     end
 
-    def set_overall_progress (value)
+    # @comment TODO: Rename to overall_progress=
+    # @param value [Float] Fraction from 0 to 1 of the overall progress that is
+    #   complete.
+    def set_overall_progress(value)
       progress_int = (value * 100).to_i
-      if !@complete and @overall_progress != progress_int
+      if !@complete && @overall_progress != progress_int
         @overall_progress = progress_int
         Qt.execute_in_main_thread(false) do
           @overall_bar.setValue(progress_int) if @overall_bar
@@ -220,6 +242,9 @@ module Cosmos
       end
     end
 
+    # @comment TODO: Rename to step_progress
+    # @return [Float] Fraction from 0 to 1 of the step progress that is
+    #   complete
     def get_step_progress
       result = nil
       Qt.execute_in_main_thread(true) do
@@ -228,6 +253,9 @@ module Cosmos
       return result
     end
 
+    # @comment TODO: Rename to overall_progress
+    # @return [Float] Fraction from 0 to 1 of the overall progress that is
+    #   complete
     def get_overall_progress
       result = nil
       Qt.execute_in_main_thread(true) do
@@ -236,7 +264,16 @@ module Cosmos
       return result
     end
 
-    def self.execute(parent, title, width = 500, height = 300, show_overall = true, show_step = true, show_text = true, show_done = true, show_cancel = true)
+    # (see #initialize)
+    def self.execute(parent,
+                     title,
+                     width = 500,
+                     height = 300,
+                     show_overall = true,
+                     show_step = true,
+                     show_text = true,
+                     show_done = true,
+                     show_cancel = true)
       # Create a non-modal dialog by default
       dialog = ProgressDialog.new(parent, title, width, height, show_overall, show_step, show_text, show_done, show_cancel)
       dialog.setModal(true)
@@ -250,8 +287,9 @@ module Cosmos
           yield dialog
         rescue Exception => error
           Qt.execute_in_main_thread(true) do
-            # If something bad happened during the yield we'll show the error but not exit the application
-            # Once the block has completed we hide and dispose the dialog to allow the main application to take over
+            # If something bad happened during the yield we'll show the error
+            # but not exit the application. Once the block has completed we
+            # hide and dispose the dialog to allow the main application to run
             dialog.hide
             ExceptionDialog.new(parent, error, "Error During Progress", false)
           end
@@ -265,12 +303,11 @@ module Cosmos
       dialog.thread = nil
       dialog.complete = true
 
-      # Need to make sure all Qt.execute_in_main_thread() have completed before disposing or
-      # we will segfault
+      # Need to make sure all Qt.execute_in_main_thread() have completed before
+      # disposing or we will segfault
       Qt::RubyThreadFix.queue.pop.call until Qt::RubyThreadFix.queue.empty?
 
       dialog.dispose
     end
-  end # class ProgressDialog
-
-end # module Cosmos
+  end
+end