dg-axlsx 2.1.0

data/lib/axlsx/workbook/workbook_view.rb

@@ -0,0 +1,78 @@
+# <xsd:complexType name="CT_BookView">
+#     <xsd:sequence>
+#       <xsd:element name="extLst" type="CT_ExtensionList" minOccurs="0" maxOccurs="1"/>
+#     </xsd:sequence>
+#     <xsd:attribute name="visibility" type="ST_Visibility" use="optional" default="visible"/>
+#     <xsd:attribute name="minimized" type="xsd:boolean" use="optional" default="false"/>
+#     <xsd:attribute name="showHorizontalScroll" type="xsd:boolean" use="optional" default="true"/>
+#     <xsd:attribute name="showVerticalScroll" type="xsd:boolean" use="optional" default="true"/>
+#     <xsd:attribute name="showSheetTabs" type="xsd:boolean" use="optional" default="true"/>
+#     <xsd:attribute name="xWindow" type="xsd:int" use="optional"/>
+#     <xsd:attribute name="yWindow" type="xsd:int" use="optional"/>
+#     <xsd:attribute name="windowWidth" type="xsd:unsignedInt" use="optional"/>
+#     <xsd:attribute name="windowHeight" type="xsd:unsignedInt" use="optional"/>
+#     <xsd:attribute name="tabRatio" type="xsd:unsignedInt" use="optional" default="600"/>
+#     <xsd:attribute name="firstSheet" type="xsd:unsignedInt" use="optional" default="0"/>
+#     <xsd:attribute name="activeTab" type="xsd:unsignedInt" use="optional" default="0"/>
+#     <xsd:attribute name="autoFilterDateGrouping" type="xsd:boolean" use="optional"
+#     default="true"/>
+# </xsd:complexType>
+
+module Axlsx
+
+  # A BookView defines the display properties for a workbook.
+  # Units for window widths and other dimensions are expressed in twips.
+  # Twip measurements are portable between different display resolutions.
+  # The formula is (screen pixels) * (20 * 72) / (logical device dpi),
+  # where the logical device dpi can be different for x and y coordinates.
+  class WorkbookView
+
+    include Axlsx::SerializedAttributes
+    include Axlsx::OptionsParser
+    include Axlsx::Accessors
+
+
+    # Creates a new BookView object
+    # @params [Hash] options  A hash of key/value pairs that will be mapped to this instances attributes.
+    # @option [Symbol] visibility Specifies visible state of the workbook window. The default value for this attribute is :visible.
+    # @option [Boolean] minimized Specifies a boolean value that indicates whether the workbook window is minimized.
+    # @option [Boolean] show_horizontal_scroll Specifies a boolean value that indicates whether to display the horizontal scroll bar in the user interface.
+    # @option [Boolean] show_vertical_scroll Specifies a boolean value that indicates whether to display the vertical scroll bar.
+    # @option [Boolean] show_sheet_tabs Specifies a boolean value that indicates whether to display the sheet tabs in the user interface.
+    # @option [Integer] tab_ratio Specifies ratio between the workbook tabs bar and the horizontal scroll bar.
+    # @option [Integer] first_sheet Specifies the index to the first sheet in this book view.
+    # @option [Integer] active_tab Specifies an unsignedInt that contains the index to the active sheet in this book view. 
+    # @option [Integer] x_window Specifies the X coordinate for the upper left corner of the workbook window. The unit of measurement for this value is twips.
+    # @option [Integer] y_window Specifies the Y coordinate for the upper left corner of the workbook window. The unit of measurement for this value is twips.
+    # @option [Integer] window_width Specifies the width of the workbook window. The unit of measurement for this value is twips.
+    # @option [Integer] window_height Specifies the height of the workbook window. The unit of measurement for this value is twips.
+    # @option [Boolean] auto_filter_date_grouping Specifies a boolean value that indicates whether to group dates when presenting the user with filtering options in the user interface.
+    def initialize(options={})
+      parse_options options
+      yield self if block_given?
+    end
+
+
+    unsigned_int_attr_accessor :x_window, :y_window, :window_width, :window_height,
+                               :tab_ratio, :first_sheet, :active_tab
+
+    validated_attr_accessor  [:visibility], :validate_view_visibility
+
+    serializable_attributes :visibility, :minimized,
+                            :show_horizontal_scroll, :show_vertical_scroll,
+                            :show_sheet_tabs, :tab_ratio, :first_sheet, :active_tab,
+                            :x_window, :y_window, :window_width, :window_height,
+                            :auto_filter_date_grouping
+
+    boolean_attr_accessor :minimized, :show_horizontal_scroll, :show_vertical_scroll,
+                          :show_sheet_tabs, :auto_filter_date_grouping
+
+
+
+    def to_xml_string(str = '')
+       str << '<workbookView '
+       serialized_attributes str
+       str << '></workbookView>'
+    end
+  end
+end

data/lib/axlsx/workbook/workbook_views.rb

@@ -0,0 +1,22 @@
+module Axlsx
+  # a simple types list of BookView objects
+  class WorkbookViews < SimpleTypedList
+
+    # creates the book views object
+    def initialize
+      super WorkbookView
+    end
+
+    # Serialize to xml
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      return if empty?
+      str << "<bookViews>"
+      each { |view| view.to_xml_string(str) }
+      str << '</bookViews>'
+    end
+  end
+end
+
+

data/lib/axlsx/workbook/worksheet/auto_filter/auto_filter.rb

@@ -0,0 +1,77 @@
+
+require 'axlsx/workbook/worksheet/auto_filter/filter_column.rb'
+require 'axlsx/workbook/worksheet/auto_filter/filters.rb'
+
+module Axlsx
+
+  #This class represents an auto filter range in a worksheet
+  class AutoFilter
+
+    # creates a new Autofilter object
+    # @param [Worksheet] worksheet
+    def initialize(worksheet)
+      raise ArgumentError, 'you must provide a worksheet' unless worksheet.is_a?(Worksheet)
+      @worksheet = worksheet
+    end
+
+    attr_reader :worksheet
+
+    # The range the autofilter should be applied to.
+    # This should be a string like 'A1:B8'
+    # @return [String]
+    attr_accessor :range
+
+    # the formula for the defined name required for this auto filter
+    # This prepends the worksheet name to the absolute cell reference
+    # e.g. A1:B2 -> 'Sheet1'!$A$1:$B$2
+    # @return [String]
+    def defined_name
+      return unless range
+      Axlsx.cell_range(range.split(':').collect { |name| worksheet.name_to_cell(name)})
+    end
+
+    # A collection of filterColumns for this auto_filter
+    # @return [SimpleTypedList]
+    def columns
+      @columns ||= SimpleTypedList.new FilterColumn
+    end
+
+    # Adds a filter column. This is the recommended way to create and manage filter columns for your autofilter.
+    # In addition to the require id and type parameters, options will be passed to the filter column during instantiation.
+    # @param [String] col_id Zero-based index indicating the AutoFilter column to which this filter information applies.
+    # @param [Symbol] filter_type A symbol representing one of the supported filter types.
+    # @param [Hash] options a hash of options to pass into the generated filter
+    # @return [FilterColumn]
+    def add_column(col_id, filter_type, options = {})
+      columns << FilterColumn.new(col_id, filter_type, options)
+      columns.last
+    end
+
+    # actually performs the filtering of rows who's cells do not
+    # match the filter.
+    def apply
+      first_cell, last_cell = range.split(':')
+      start_point = Axlsx::name_to_indices(first_cell)
+      end_point = Axlsx::name_to_indices(last_cell)
+      # The +1 is so we skip the header row with the filter drop downs
+      rows = worksheet.rows[(start_point.last+1)..end_point.last] || []
+
+      column_offset = start_point.first
+      columns.each do |column|
+        rows.each do |row|
+          next if row.hidden
+          column.apply(row, column_offset)
+        end
+      end
+    end
+    # serialize the object
+    # @return [String]
+    def to_xml_string(str='')
+      return unless range
+      str << "<autoFilter ref='#{range}'>"
+      columns.each { |filter_column| filter_column.to_xml_string(str) }
+      str << "</autoFilter>"
+    end
+
+  end
+end

data/lib/axlsx/workbook/worksheet/auto_filter/filter_column.rb

@@ -0,0 +1,94 @@
+module Axlsx
+  # The filterColumn collection identifies a particular column in the AutoFilter
+  # range and specifies filter information that has been applied to this column.
+  # If a column in the AutoFilter range has no criteria specified,
+  # then there is no corresponding filterColumn collection expressed for that column.
+  class FilterColumn
+
+    include Axlsx::OptionsParser
+    include Axlsx::SerializedAttributes
+
+    # Creates a new FilterColumn object
+    # @note This class yeilds its filter object as that is where the vast majority of processing will be done
+    # @param [Integer|Cell] col_id The zero based index for the column to which this filter will be applied
+    # @param [Symbol] filter_type The symbolized class name of the filter to apply to this column.
+    # @param [Hash] options options for this object and the filter
+    # @option [Boolean] hidden_button @see hidden_button
+    # @option [Boolean] show_button @see show_button
+    def initialize(col_id, filter_type, options = {})
+      RestrictionValidator.validate 'FilterColumn.filter', FILTERS, filter_type
+      #Axlsx::validate_unsigned_int(col_id)
+      self.col_id = col_id
+      parse_options options
+      @filter = Axlsx.const_get(Axlsx.camel(filter_type)).new(options)
+      yield @filter if block_given?
+    end
+
+    serializable_attributes :col_id, :hidden_button, :show_button
+
+    # Allowed filters
+    FILTERS =  [:filters] #, :top10, :custom_filters, :dynamic_filters, :color_filters, :icon_filters]
+
+    # Zero-based index indicating the AutoFilter column to which this filter information applies.
+    # @return [Integer]
+    attr_reader :col_id
+
+    # The actual filter being dealt with here
+    # This could be any one of the allowed filter types
+    attr_reader :filter
+
+    # Flag indicating whether the filter button is visible.
+    # When the cell containing the filter button is merged with another cell,
+    # the filter button can be hidden, and not drawn.
+    # @return [Boolean]
+    def show_button
+      @show_button ||= true
+    end
+
+    # Flag indicating whether the AutoFilter button for this column is hidden.
+    # @return [Boolean]
+    def hidden_button
+      @hidden_button ||= false
+    end
+
+    # Sets the col_id attribute for this filter column.
+    # @param [Integer | Cell] column_index The zero based index of the column to which this filter applies. 
+    #                         When you specify a cell, the column index will be read off the cell
+    # @return [Integer]
+    def col_id=(column_index)
+      column_index = column_index.col if column_index.is_a?(Cell)
+      Axlsx.validate_unsigned_int column_index
+      @col_id = column_index
+    end
+
+    # Apply the filters for this column
+    # @param [Array] row A row from a worksheet that needs to be
+    # filtered.
+    def apply(row, offset)
+      row.hidden = @filter.apply(row.cells[offset+col_id.to_i])
+    end
+    # @param [Boolean] hidden Flag indicating whether the AutoFilter button for this column is hidden.
+    # @return [Boolean]
+    def hidden_button=(hidden)
+      Axlsx.validate_boolean hidden
+      @hidden_button = hidden
+    end
+
+    # Flag indicating whether the AutoFilter button is show. This is
+    # undocumented in the spec, but exists in the schema file as an
+    # optional attribute.
+    # @param [Boolean] show Show or hide the button
+    # @return [Boolean]
+    def show_button=(show)
+      Axlsx.validate_boolean show
+      @show_botton = show
+    end
+
+    # Serialize the object to xml
+    def to_xml_string(str='')
+      str << "<filterColumn #{serialized_attributes}>"
+      @filter.to_xml_string(str)
+      str << "</filterColumn>"
+    end
+  end
+end

data/lib/axlsx/workbook/worksheet/auto_filter/filters.rb

@@ -0,0 +1,244 @@
+module Axlsx
+
+  # When multiple values are chosen to filter by, or when a group of date values are chosen to filter by, 
+  # this object groups those criteria together.
+  class Filters
+    include Axlsx::OptionsParser
+    include Axlsx::SerializedAttributes
+
+    # Creates a new Filters object
+    # @param [Hash] options Options used to set this objects attributes and
+    #                       create filter and/or date group items
+    # @option [Boolean] blank @see blank
+    # @option [String] calendar_type @see calendar_type
+    # @option [Array] filter_items An array of values that will be used to create filter objects.
+    # @option [Array] date_group_items An array of hases defining date group item filters to apply.
+    # @note The recommended way to interact with filter objects is via AutoFilter#add_column
+    # @example
+    #   ws.auto_filter.add_column(0, :filters, :blank => true, :calendar_type => 'japan', :filter_items => [100, 'a'])
+    def initialize(options={})
+      parse_options options
+    end
+
+    serializable_attributes :blank, :calendar_type
+
+    # Allowed calendar types
+    CALENDAR_TYPES = %w(gregorian gregorianUs gregorianMeFrench gregorianArabic hijri hebrew taiwan japan thai korea saka gregorianXlitEnglish gregorianXlitFrench none)
+
+    # Flag indicating whether to filter by blank.
+    # @return [Boolean]
+    attr_reader :blank
+
+    # Calendar type for date grouped items. 
+    # Used to interpret the values in dateGroupItem.
+    # This is the calendar type used to evaluate all dates in the filter column,
+    # even when those dates are not using the same calendar system / date formatting.
+    attr_reader :calendar_type
+
+    # Tells us if the row of the cell provided should be filterd as it
+    # does not meet any of the specified filter_items or
+    # date_group_items restrictions.
+    # @param [Cell] cell The cell to test against items
+    # TODO implement this for date filters as well!
+    def apply(cell)
+      return false unless cell
+      filter_items.each do |filter|
+        return false if cell.value == filter.val
+      end
+      true
+    end
+
+    # The filter values in this filters object
+    def filter_items
+      @filter_items ||= []
+    end
+
+    # the date group values in this filters object
+    def date_group_items
+      @date_group_items ||= []
+    end
+
+    # @see calendar_type
+    # @param [String] calendar The calendar type to use. This must be one of the types defined in CALENDAR_TYPES
+    # @return [String]
+    def calendar_type=(calendar)
+      RestrictionValidator.validate 'Filters.calendar_type', CALENDAR_TYPES, calendar
+      @calendar_type = calendar
+    end
+
+    # Set the value for blank
+    # @see blank
+    def blank=(use_blank)
+      Axlsx.validate_boolean use_blank
+      @blank = use_blank
+    end
+
+    # Serialize the object to xml
+    def to_xml_string(str = '')
+      str << "<filters #{serialized_attributes}>"
+      filter_items.each {  |filter| filter.to_xml_string(str) }
+      date_group_items.each { |date_group_item| date_group_item.to_xml_string(str) }
+      str << '</filters>'
+    end
+
+    # not entirely happy with this. 
+    # filter_items should be a simple typed list that overrides << etc
+    # to create Filter objects from the inserted values. However this
+    # is most likely so rarely used...(really? do you know that?)
+    def filter_items=(values)
+      values.each do |value|
+        filter_items << Filter.new(value)
+      end
+    end
+
+    # Date group items are date group filter items where you specify the
+    # date_group and a value for that option as part of the auto_filter
+    # @note This can be specified, but will not be applied to the date
+    # values in your workbook at this time.
+    def date_group_items=(options)
+      options.each do |date_group|
+        raise ArgumentError, "date_group_items should be an array of hashes specifying the options for each date_group_item" unless date_group.is_a?(Hash)
+        date_group_items << DateGroupItem.new(date_group)
+      end
+    end
+
+    # This class expresses a filter criteria value.
+    class Filter
+
+      # Creates a new filter value object
+      # @param [Any] value   The value of the filter. This is not restricted, but
+      #                       will be serialized via to_s so if you are passing an object
+      #                       be careful.
+      def initialize(value)
+        @val = value
+      end
+
+
+      #Filter value used in the criteria.
+      attr_accessor :val
+
+      # Serializes the filter value object
+      # @param [String] str The string to concact the serialization information to.
+      def to_xml_string(str = '')
+        str << "<filter val='#{@val.to_s}' />"
+      end
+    end
+
+
+    # This collection is used to express a group of dates or times which are
+    # used in an AutoFilter criteria. Values are always written in the calendar
+    # type of the first date encountered in the filter range, so that all
+    # subsequent dates, even when formatted or represented by other calendar
+    # types, can be correctly compared for the purposes of filtering.
+    class DateGroupItem
+      include Axlsx::OptionsParser
+include Axlsx::SerializedAttributes
+
+      # Creates a new DateGroupItem
+      # @param [Hash] options A hash of options to use when
+      # instanciating the object
+      # @option [String] date_time_grouping the part of the date this
+      # filter should apply for grouping
+      # @option [Integer|String] year @see year
+      # @option [Integer] month @see month
+      # @option [Integer] day @see day
+      # @option [Integer] hour @see hour
+      # @option [Integer] minute @see minute
+      # @option [Integer] second @see second
+      def initialize(options={})
+        raise ArgumentError,  "You must specify a year for date time grouping" unless options[:year]
+        raise ArgumentError, "You must specify a date_time_grouping when creating a DateGroupItem for auto filter" unless options[:date_time_grouping]
+        parse_options options
+      end
+
+      serializable_attributes :date_time_grouping, :year, :month, :day, :hour, :minute, :second
+
+      # Allowed date time groupings
+      DATE_TIME_GROUPING = %w(year month day hour minute second)
+
+      # Grouping level
+      # This must be one of year, month, day, hour, minute or second.
+      # @return [String]
+      attr_reader :date_time_grouping
+
+      # Year (4 digits)
+      # @return [Integer|String]
+      attr_reader :year
+
+      # Month (1..12)
+      # @return [Integer]
+      attr_reader :month
+
+      # Day (1-31)
+      # @return [Integer]
+      attr_reader :day
+
+      # Hour (0..23)
+      # @return [Integer]
+      attr_reader :hour
+
+      # Minute (0..59(
+      # @return [Integer]
+      attr_reader :minute
+
+      # Second (0..59)
+      # @return [Integer]
+      attr_reader :second
+
+      # The year value for the date group item
+      # This must be a four digit value
+      def year=(value)
+        RegexValidator.validate "DateGroupItem.year", /\d{4}/, value
+        @year = value
+      end
+
+      # The month value for the date group item
+      # This must be between 1 and 12
+      def month=(value)
+        RangeValidator.validate "DateGroupItem.month", 0, 12, value
+        @month = value
+      end
+
+      # The day value for the date group item
+      # This must be between 1 and 31 
+      # @note no attempt is made to ensure the date value is valid for any given month
+      def day=(value)
+        RangeValidator.validate "DateGroupItem.day", 0, 31, value
+        @day = value
+      end
+
+      # The hour value for the date group item
+      # # this must be between 0 and 23
+      def hour=(value)
+        RangeValidator.validate "DateGroupItem.hour", 0, 23, value
+        @hour = value
+      end
+
+      # The minute value for the date group item
+      # This must be between 0 and 59
+      def minute=(value)
+        RangeValidator.validate "DateGroupItem.minute", 0, 59, value
+        @minute = value
+      end
+
+      # The second value for the date group item
+      # This must be between 0 and 59
+      def second=(value)
+        RangeValidator.validate "DateGroupItem.second", 0, 59, value
+        @second = value
+      end
+
+      # The date time grouping for this filter.
+      def date_time_grouping=(grouping)
+        RestrictionValidator.validate 'DateGroupItem.date_time_grouping', DATE_TIME_GROUPING, grouping.to_s
+        @date_time_grouping = grouping.to_s
+      end
+
+      # Serialize the object to xml
+      # @param [String] str The string object this serialization will be concatenated to.
+      def to_xml_string(str = '')
+        serialized_tag('dateGroupItem', str)
+      end
+    end
+  end
+end