robust_excel_ole 1.0.1 → 1.0.2

data/README_detail.rdoc

@@ -5,7 +5,7 @@ It supports simultaneously running Excel instances and user interactions.
 RobustExcelOle deals with various cases of Excel and user behaviour,
 and implements workarounds for some Excel bugs.
 The gem provides convenient methods for common tasks, and facilitates referenced libraries.
-It supports Excel 2010 and Excel 2007.
+It supports Excel 2010.
 
 RobustExcelOle works by sending VBA methods via Win32OLE.
 Moreover, it implements a management system and keeps track of Excel files and Excel instances.
@@ -42,7 +42,7 @@ Options are the following:
 
  +:force+:: no matter whether the workbook was open before, use the properties stated in +:force+
 
- +:excel+ and +:visible+ are options stated in +:default+ and +:force+
+ +:excel+ and +:visible+ are options stated in +:default+ or +:force+
 
  +:excel+::          specifies the Excel instance. 
  +:visible+::        makes the workbook visible or invisible
@@ -115,6 +115,10 @@ If you want to open the workbook and make its window visible, then use
 
   book = Book.open('workbook.xls', :force => {:visible => true})
 
+or
+
+  book = Book.open('workbook.xls', :visible => true)
+
 You can combine options, e.g. 
 
   Book.open('workbook.xls', :force => {:excel => :new, :visible => true})
@@ -216,15 +220,13 @@ If a workbook blocks the workbook that should be saved, then the former one can
 
 === Unobtrusively modifying a workbook
 
-The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable. 
+The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable, visible or invisible, calculation mode is automatic or manual, and checking compatibility is turned on or off. 
 
-One option chooses the Excel instance in which a closed workbook is opened. The option +:current+ (or +:active+, or +:reuse) (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed workbook.
+One option chooses the Excel instance in which a closed workbook is opened. The option +:current+ (or +:active+, or +:reuse) (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused.  Moreover, an Excel instance can be given directly where to open the closed workbook.
 
 Options are the following:
 
 +:current+ (or +:active, or +:reuse+:): (default) : open a closed workbook in the Excel instance where it was opened most recently, if such an Excel instance exists, otherwise open it in the current (first opened) Excel instance
-+:hidden+::          : open a closed workbook in one separate Excel instance that is not visible and has no displayalerts
-<excel-instance> : open a closed workbooks in the given Excel instance
                
 +:read_only+:: Open the workbook unobtrusively for reading only  (default: false)
 +:readonly_excel+::  if the workbook is opened only as ReadOnly and shall be modified, then
@@ -232,8 +234,6 @@ Options are the following:
                      false (default) open it as writable in another running excel instance, if it exists, 
                                      otherwise open in a new excel instance
 +:keep_open+::          let the workbook open after unobtrusively opening (default: false)
-+:visible+::            make the window of the workbook visible (default: false)
-+:check_compatibility+:: checks compatibility when saving
 
   Book.unobtrusively('workbook.xls') do |book|
     # some modification
@@ -404,13 +404,13 @@ or
 
 === Getting and setting the contents of a named range in a Worksheet directly
 
-You get the value of a range with
+You get the value of a range of a locally defined name with
 
   sheet.rangeval(name)
 
-and set the value of a range.
+and set the value of this range by
 
-  book.set_rangeval(name,value)
+  sheet.set_rangeval(name,value)
 
 === Adding and copying a worksheet.
 
@@ -464,7 +464,7 @@ The option +:calculation+ specifies, whether the calculation mode is being force
 
 You can also promote an Excel instance represented as WIN32OLE object to an Excel object.
 
-  excel = Excel.new(win32ole_object)
+  excel = Excel.new(win32ole_object, :visible => true)
 
 === Making a Excel visible or invisible
 
@@ -510,6 +510,14 @@ You can turn off and off DisplayAlerts in a block.
 
   excel1.workbooks_visible false   
 
+=== Setting options
+
+You can set all options in a given Excel instance
+
+  e1 = Excel.current
+
+  e1.set_options(:visible => true, :displayalerts => true)
+
 === Bringing an Excel instance to the foreground
 
   excel1.focus
@@ -591,13 +599,21 @@ or
 
   excel.set_nameval(name,value)
 
+=== Retaining the saved-status of all workbooks
+
+You can operate in some Excel instance and retain the saved-status of all workbooks.
+
+  excel.retain_saved_workbooks do
+    ...
+  end  
+
 === Getting and setting the contents of a named range in an Excel application directly
 
-You can get the value of a range
+You can get the value of a range of a locally defined name by
 
   excel.rangeval(name)
 
-and set the value of a range.
+and set the value of this range with
 
   excel.set_rangeval(name,value)
   
@@ -768,6 +784,7 @@ Some features in RobustExcelOle that are not compatible with wrap_excel:
 * +save_as+ instead of +save+.
 * position of cells and number of sheets are based on 1 instead of 0
 
+Excel 2007 was supported until version 0.3.6.
 
 === Want to do more things
 

data/lib/robust_excel_ole/book.rb

@@ -212,6 +212,7 @@ module RobustExcelOle
 
   public
 
+=begin
     # work in progress#
     def self.open_in_current_excel(file, opts = { }) # :nodoc: # 
       options = DEFAULT_OPEN_OPTS.merge(opts)
@@ -230,6 +231,7 @@ module RobustExcelOle
       workbook.CheckCompatibility = options[:check_compatibility]
       workbook
     end
+=end
 
     def ensure_excel(options)   # :nodoc: #
       if @excel && @excel.alive?
@@ -249,6 +251,7 @@ module RobustExcelOle
     def ensure_workbook(file, options)     # :nodoc: #
       file = @stored_filename ? @stored_filename : file
       raise(FileNameNotGiven, "filename is nil") if file.nil?
+      raise(FileNotFound, "file #{General::absolute_path(file).inspect} is a directory") if File.directory?(file)
       unless File.exist?(file)
         if options[:if_absent] == :create
           @ole_workbook = excel_class.current.generate_workbook(file)
@@ -303,8 +306,7 @@ module RobustExcelOle
             when :alert, :excel
               @excel.with_displayalerts(true) { open_or_create_workbook(file,options) }
             when :new_excel
-              excel_options[:reuse] = false
-              @excel = excel_class.new(excel_options)
+              @excel = excel_class.new(:reuse => false)
               open_or_create_workbook(file, options)
             else
               raise OptionInvalid, ":if_unsaved: invalid option: #{options[:if_unsaved].inspect}"
@@ -333,16 +335,15 @@ module RobustExcelOle
             end
           end
           begin
-            with_workaround_linked_workbooks_excel2007(options) do            
+            with_workaround_linked_workbooks_excel2007(options) do
               workbooks.Open(filename, { 'ReadOnly' => options[:read_only] ,
                                          'UpdateLinks' => updatelinks_vba(options[:update_links]) })
             end
           rescue WIN32OLERuntimeError => msg
-            if msg.message =~ /800A03EC/
-              raise ExcelError, "user canceled or runtime error #{msg.message}"
-            else 
-              raise UnexpectedError, "unexpected WIN32OLERuntimeError: #{msg.message}"
-            end 
+            # for Excel2007: for option :if_unsaved => :alert and user cancels: this error appears?
+            # if yes: distinguish these events
+            #raise
+            trace "WIN32OLERuntimeError: #{msg.message}" 
           end
           begin
             # workaround for bug in Excel 2010: workbook.Open does not always return the workbook when given file name
@@ -386,8 +387,9 @@ module RobustExcelOle
     # opening and closing a dummy workbook if Excel has no workbooks.
     # delay: with visible: 0.2 sec, without visible almost none
     def with_workaround_linked_workbooks_excel2007(options)
+      old_visible_value = @excel.Visible
       workbooks = @excel.Workbooks
-      workaround_condition = @excel.Version.split(".").first.to_i >= 12 && workbooks.Count == 0
+      workaround_condition = @excel.Version.split(".").first.to_i == 12 && workbooks.Count == 0
       if workaround_condition
         workbooks.Add 
         @excel.calculation = options[:calculation].nil? ? @excel.calculation : options[:calculation] 
@@ -396,7 +398,8 @@ module RobustExcelOle
         #@excel.with_displayalerts(update_links_opt == :alert ? true : @excel.displayalerts) do
         yield self
       ensure
-        @excel.with_displayalerts(false){workbooks.Item(1).Close} if workaround_condition           
+        @excel.with_displayalerts(false){workbooks.Item(1).Close} if workaround_condition    
+        @excel.visible = old_visible_value       
       end
     end
        
@@ -473,87 +476,65 @@ module RobustExcelOle
       unobtrusively(*args, &block)
     end
 
-    # allows to modify a workbook such that its state (open/close, saved/unsaved, readonly/writable) remains unchanged
+    # allows to read or modify a workbook such that its state remains unchanged
+    # state comprises: open, saved, writable, visible, calculation mode, check compatibility 
     # @param [String] file        the file name
-    # @param [Hash]   if_closed   an option
     # @param [Hash]   opts        the options
-    # @option opts [Variant] :if_closed  :current (or :reuse, :active) (default), :hidden or a Excel instance
-    # @option opts [Boolean] :read_only whether the file is opened for read-only
+    # @option opts [Variant] :if_closed  :current (default), :new or an Excel instance
+    # @option opts [Boolean] :read_only whether the workbook is opened for read-only
     # @option opts [Boolean] :readonly_excel behaviour when workbook is opened read-only and shall be modified
-    # @option opts [Boolean] :keep_open whether the workbook shall be kept open after unobtrusively opening
-    # @option opts [Boolean] :visible        true, or false (default) 
-    #  options: 
-    #   :if_closed :   if the workbook is closed, then open it in
-    #                    :current (or :active, :reuse) -> the Excel instance of the workbook, if it exists, 
-    #                                                     reuse another Excel, otherwise          
-    #                    :hidden -> a separate Excel instance that is not visible and has no displayalerts
-    #                    <excel-instance> -> the given Excel instance
-    #  :readonly_excel:  if the workbook is opened only as ReadOnly and shall be modified, then
-    #                    true:  closes it and open it as writable in the Excel instance where it was open so far
-    #                    false (default)   opens it as writable in another running excel instance, if it exists,
-    #                                      otherwise open in a new Excel instance.
-    #  :visible, :read_only, :update_links, :check_compatibility : see options in #open
+    #               true:  closes it and open it as writable in the Excel instance where it was open so far
+    #               false (default)  opens it as writable in another running excel instance, if it exists,
+    #                                otherwise open in a new Excel instance.
+    # @option opts [Boolean] :keep_open whether the workbook shall be kept open after unobtrusively opening 
     # @return [Book] a workbook
-    def self.unobtrusively(file, if_closed = nil, opts = { }, &block) 
-      if if_closed.is_a? Hash
-        opts = if_closed
-        if_closed = nil
-      end
-      if_closed = :current if (if_closed == :reuse || if_closed == :active)
-      if_closed = :current unless if_closed
-      options = process_options(opts)
-      opts = {:readonly_excel => false,:keep_open => false}.merge(opts)
+
+    # state = [:open, :saved, :writable, :visible, :calculation, :check_compatibility]
+
+    def self.unobtrusively(file, opts = { }, &block) 
+      options = {:if_closed => :current, 
+                 :read_only => false,
+                 :readonly_excel => false,
+                 :keep_open => false}.merge(opts)
       book = bookstore.fetch(file, :prefer_writable => (not options[:read_only]))
-      was_not_alive_or_nil = book.nil? || (not book.alive?)
-      workbook = book.excel.Workbooks.Item(File.basename(file)) rescue nil
-      was_saved = was_not_alive_or_nil ? true : book.saved
-      was_writable = book.writable unless was_not_alive_or_nil
-      was_check_compatibility = book.CheckCompatibility unless was_not_alive_or_nil     
+      was_open = book && book.alive?
+      if was_open
+        was_saved = book.saved
+        was_writable = book.writable
+        was_visible = book.visible
+        was_calculation = book.calculation
+        was_check_compatibility = book.check_compatibility
+      end     
       begin 
         book = 
-          if was_not_alive_or_nil 
-            case if_closed
-            when :current
-              open(file, :default => {:excel => :current}, :read_only => options[:read_only])
-            when :hidden 
-              open(file, :force => {:excel => bookstore.hidden_excel}, :read_only => options[:read_only])
-            else 
-              open(file, :force => {:excel => if_closed}, :read_only => options[:read_only])
-            end
-          else
-            if was_writable || options[:read_only]
-              book
+          if was_open 
+            if (not was_writable) && (not options[:read_only])
+              open(file, :force => {:excel => (options[:readonly_excel] ? book.excel : :new)}, :read_only => false)
             else
-              options[:readonly_excel] ? open(file, :force => {:excel => book.excel}, :read_only => options[:read_only]) : 
-                                         open(file, :force => {:excel => :new}, :read_only => options[:read_only])
+              book
             end
-          end
-        #book.excel.visible = options[:force][:visible] unless options[:force].nil? or options[:force][:visible].nil?
-        options = process_options(options)
-        if options[:force][:visible].nil? && (not options[:default][:visible].nil?)
-          if book.excel.created   
-            book.visible = options[:default][:visible] 
           else
-            book.window_visible = options[:default][:visible]
+            open(file, :force => {:excel => options[:if_closed]}, :read_only => false)
           end
-        else
-          book.visible = options[:force][:visible] unless options[:force][:visible].nil?
-        end
-        book.CheckCompatibility = options[:check_compatibility] unless options[:check_compatibility].nil?
         yield book
       ensure
-        if book && book.alive?          
+        if book && book.alive?
           unless book.saved
             book.save unless options[:read_only]
-            book.Saved = true if was_saved && options[:read_only]
-            book.Saved = false unless was_saved || options[:read_only]
+            book.Saved = true if (was_saved || (not was_open)) && options[:read_only]
+            book.Saved = false if (not was_saved) && (not options[:read_only]) && was_open
           end
-          # book was open, readonly and should be modified
-          unless was_not_alive_or_nil || options[:read_only] || was_writable || (not options[:readonly_excel])
-            open(file, :force => {:excel => book.excel}, :if_obstructed => :new_excel, :read_only => true)
-          end
-          book.CheckCompatibility = was_check_compatibility unless was_check_compatibility.nil?
-          book.close if was_not_alive_or_nil && (not options[:keep_open])
+          if was_open
+            if (not was_writable) && (not options[:read_only]) && options[:readonly_excel]
+              book.close
+              open(file, :force => {:excel => book.excel}, :if_obstructed => :new_excel, :read_only => true)
+            end         
+            book.excel.calculation = was_calculation
+            book.CheckCompatibility = was_check_compatibility
+            #book.visible = was_visible  # not necessary
+          end          
+          
+          book.close unless was_open || options[:keep_open]
         end
       end
     end
@@ -851,40 +832,6 @@ module RobustExcelOle
       @ole_workbook.Activate
     end
 
-    # returns true, if the workbook is visible, false otherwise 
-    def visible
-      @excel.visible && @ole_workbook.Windows(@ole_workbook.Name).Visible
-    end
-
-    # makes both the Excel instance and the window of the workbook visible, or the window invisible
-    # @param [Boolean] visible_value determines whether the workbook shall be visible
-    def visible= visible_value
-      @excel.visible = true if visible_value
-      self.window_visible = visible_value
-    end
-
-    # returns true, if the window of the workbook is set to visible, false otherwise
-    def window_visible
-      return @ole_workbook.Windows(@ole_workbook.Name).Visible
-    end
-
-    # makes the window of the workbook visible or invisible
-    # @param [Boolean] visible_value determines whether the window of the workbook shall be visible
-    def window_visible= visible_value
-      retain_saved do
-        @ole_workbook.Windows(@ole_workbook.Name).Visible = visible_value if @ole_workbook.Windows.Count > 0
-      end
-    end
-
-#    def visible= visible_value
-#      retain_saved do
-#        @excel.visible = true if visible_value
-#        if @ole_workbook.Windows.Count > 0
-#          @ole_workbook.Windows(@ole_workbook.Name).Visible = visible_value 
-#        end
-#      end
-#    end
-
     # returns true, if the workbook reacts to methods, false otherwise
     def alive?
       begin 
@@ -910,6 +857,39 @@ module RobustExcelOle
       @ole_workbook.Saved if @ole_workbook
     end
 
+    def calculation
+      @excel.calculation if @ole_workbook
+    end
+
+    def check_compatibility
+      @ole_workbook.CheckCompatibility if @ole_workbook
+    end
+
+        # returns true, if the workbook is visible, false otherwise 
+    def visible
+      @excel.visible && @ole_workbook.Windows(@ole_workbook.Name).Visible
+    end
+
+    # makes both the Excel instance and the window of the workbook visible, or the window invisible
+    # @param [Boolean] visible_value determines whether the workbook shall be visible
+    def visible= visible_value
+      @excel.visible = true if visible_value
+      self.window_visible = visible_value
+    end
+
+    # returns true, if the window of the workbook is set to visible, false otherwise
+    def window_visible
+      return @ole_workbook.Windows(@ole_workbook.Name).Visible
+    end
+
+    # makes the window of the workbook visible or invisible
+    # @param [Boolean] visible_value determines whether the window of the workbook shall be visible
+    def window_visible= visible_value
+      retain_saved do
+        @ole_workbook.Windows(@ole_workbook.Name).Visible = visible_value if @ole_workbook.Windows.Count > 0
+      end
+    end
+
     # @return [Boolean] true, if the full book names and excel Instances are identical, false otherwise  
     def == other_book
       other_book.is_a?(Book) &&
@@ -941,10 +921,6 @@ module RobustExcelOle
       "#<Book: " + "#{"not alive " unless alive?}" + "#{File.basename(self.filename) if alive?}" + " #{@ole_workbook} #{@excel}"  + ">"
     end
 
-    def self.in_context(klass)  # :nodoc: #
-      
-    end
-
     def self.excel_class    # :nodoc: #
       @excel_class ||= begin
         module_name = self.parent_name

data/lib/robust_excel_ole/excel.rb

@@ -47,7 +47,7 @@ module RobustExcelOle
     end
 
     # returns an Excel instance  
-    # given a WIN32OLE object representing an Excel instance, or a Hash representing options
+    # @param [Win32Ole] (optional) a WIN32OLE object representing an Excel instance
     # @param [Hash] options the options
     # @option options [Boolean] :reuse      
     # @option options [Boolean] :visible
@@ -63,13 +63,14 @@ module RobustExcelOle
     #                    or is not being forced (default: nil)
     #  :screenupdating  turns on or off screen updating (default: true)
     # @return [Excel] an Excel instance
-    def self.new(options = {})
-      if options.is_a? WIN32OLE
-        ole_xl = options
-      else
-        options = {:reuse => true}.merge(options)
-        ole_xl = current_excel if options[:reuse] == true
-      end
+    def self.new(win32ole_excel = nil, options = { })
+      if win32ole_excel.is_a? Hash
+        options = win32ole_excel
+        win32ole_excel = nil
+      end
+      ole_xl = win32ole_excel unless win32ole_excel.nil?
+      options = {:reuse => true}.merge(options)
+      ole_xl = current_excel if options[:reuse] == true
       ole_xl ||= WIN32OLE.new('Excel.Application')
       hwnd = ole_xl.HWnd
       stored = hwnd2excel(hwnd)
@@ -136,6 +137,10 @@ module RobustExcelOle
       self 
     end
 
+    def set_options(options)
+      self.class.new(@ole_excel, options)
+    end
+
   private
     
     # returns a Win32OLE object that represents a Excel instance to which Excel connects
@@ -156,6 +161,21 @@ module RobustExcelOle
 
   public
 
+    # retain the saved status of all workbooks
+    def retain_saved_workbooks
+      saved = []
+      @ole_excel.Workbooks.each {|w| saved << w.Saved}
+      begin
+        yield self
+      ensure
+        i = 0
+        @ole_excel.Workbooks.each do |w|
+          w.Saved = saved[i] if saved[i]
+          i = i + 1 
+        end
+      end
+    end
+
     def self.contains_unsaved_workbooks?
       excel = begin
         Excel.current
@@ -513,14 +533,22 @@ module RobustExcelOle
     end
 
     # sets calculation mode
+    # retains the saved-status of the workbooks when set to manual
     def calculation= calculation_mode
       return if calculation_mode.nil?
       @calculation = calculation_mode
       calc_mode_changable = @ole_excel.Workbooks.Count > 0 &&  @ole_excel.Calculation.is_a?(Fixnum)
       if calc_mode_changable
+        if calculation_mode == :manual then
+          saved = []
+          (1..@ole_excel.Workbooks.Count).each {|i| saved << @ole_excel.Workbooks(i).Saved}
+        end
         @ole_excel.CalculateBeforeSave = false
         @ole_excel.Calculation = 
           (calculation_mode == :automatic) ? XlCalculationAutomatic : XlCalculationManual 
+        if calculation_mode == :manual then
+          (1..@ole_excel.Workbooks.Count).each {|i| @ole_excel.Workbooks(i).Saved = true if saved[i-1]}
+        end
       end    
     end
 
@@ -630,7 +658,7 @@ module RobustExcelOle
       end
     end    
 
-    # returns the contents of a range with a defined local name
+    # returns the contents of a range with a locally defined name
     # evaluates the formula if the contents is a formula
     # if no contents could be returned, then return default value, if provided, raise error otherwise
     # @param  [String]      name      the range name
@@ -655,7 +683,7 @@ module RobustExcelOle
       value
     end
 
-    # assigns a value to a range given a defined local name
+    # assigns a value to a range given a locally defined name
     # @param [String]  name   the range name
     # @param [Variant] value  the assigned value
     def set_rangeval(name,value)