write_xlsx 0.64.1 → 0.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. checksums.yaml +4 -4
  2. data/README.rdoc +10 -1
  3. data/examples/conditional_format.rb +251 -18
  4. data/examples/demo.rb +2 -3
  5. data/examples/macros.rb +42 -0
  6. data/examples/outline_collapsed.rb +160 -0
  7. data/examples/republic.png +0 -0
  8. data/examples/shape3.rb +2 -2
  9. data/examples/shape4.rb +5 -5
  10. data/examples/shape5.rb +6 -6
  11. data/examples/shape6.rb +6 -6
  12. data/examples/shape7.rb +11 -11
  13. data/examples/shape8.rb +10 -10
  14. data/examples/shape_all.rb +0 -0
  15. data/examples/vbaProject.bin +0 -0
  16. data/lib/write_xlsx/chart.rb +656 -56
  17. data/lib/write_xlsx/chartsheet.rb +26 -2
  18. data/lib/write_xlsx/format.rb +50 -27
  19. data/lib/write_xlsx/formats.rb +32 -0
  20. data/lib/write_xlsx/package/packager.rb +45 -238
  21. data/lib/write_xlsx/package/table.rb +9 -18
  22. data/lib/write_xlsx/package/xml_writer_simple.rb +26 -9
  23. data/lib/write_xlsx/sheets.rb +223 -0
  24. data/lib/write_xlsx/sparkline.rb +140 -4
  25. data/lib/write_xlsx/version.rb +1 -1
  26. data/lib/write_xlsx/workbook.rb +34 -121
  27. data/lib/write_xlsx/worksheet/data_validation.rb +291 -0
  28. data/lib/write_xlsx/worksheet/hyperlink.rb +111 -0
  29. data/lib/write_xlsx/worksheet/page_setup.rb +170 -0
  30. data/lib/write_xlsx/worksheet.rb +1112 -1334
  31. data/test/helper.rb +1 -1
  32. data/test/package/styles/test_styles_01.rb +1 -10
  33. data/test/package/styles/test_styles_02.rb +1 -10
  34. data/test/package/styles/test_styles_03.rb +1 -10
  35. data/test/package/styles/test_styles_04.rb +1 -10
  36. data/test/package/styles/test_styles_05.rb +1 -10
  37. data/test/package/styles/test_styles_06.rb +1 -10
  38. data/test/package/styles/test_styles_07.rb +1 -10
  39. data/test/package/styles/test_styles_08.rb +1 -10
  40. data/test/package/styles/test_styles_09.rb +1 -10
  41. data/test/perl_output/conditional_format.xlsx +0 -0
  42. data/test/perl_output/outline_collapsed.xlsx +0 -0
  43. data/test/perl_output/protection.xlsx +0 -0
  44. data/test/regression/test_chart_gap01.rb +47 -0
  45. data/test/regression/test_chart_gap02.rb +47 -0
  46. data/test/regression/test_chart_gap03.rb +47 -0
  47. data/test/regression/test_format05.rb +26 -0
  48. data/test/regression/test_rich_string12.rb +32 -0
  49. data/test/regression/xlsx_files/chart_gap01.xlsx +0 -0
  50. data/test/regression/xlsx_files/chart_gap02.xlsx +0 -0
  51. data/test/regression/xlsx_files/chart_gap03.xlsx +0 -0
  52. data/test/regression/xlsx_files/format05.xlsx +0 -0
  53. data/test/regression/xlsx_files/rich_string12.xlsx +0 -0
  54. data/test/test_example_match.rb +253 -20
  55. data/test/worksheet/test_set_column.rb +25 -0
  56. data/test/worksheet/test_worksheet_03.rb +1 -1
  57. data/test/worksheet/test_worksheet_04.rb +1 -1
  58. data/test/worksheet/test_write_array_formula_01.rb +7 -0
  59. data/test/worksheet/test_write_col_breaks.rb +2 -2
  60. data/test/worksheet/test_write_col_info.rb +8 -8
  61. data/test/worksheet/test_write_conditional_formatting.rb +4 -4
  62. data/test/worksheet/test_write_formula_does_not_change_formula_string.rb +18 -0
  63. data/test/worksheet/test_write_header_footer.rb +8 -3
  64. data/test/worksheet/test_write_hyperlink.rb +10 -5
  65. data/test/worksheet/test_write_merge_cells.rb +6 -6
  66. data/test/worksheet/test_write_page_set_up_pr.rb +1 -1
  67. data/test/worksheet/test_write_page_setup.rb +1 -1
  68. data/test/worksheet/test_write_row_breaks.rb +2 -2
  69. data/test/worksheet/test_write_row_element.rb +1 -1
  70. data/test/worksheet/test_write_sheet_pr.rb +2 -2
  71. data/test/worksheet/test_write_sheet_view.rb +0 -9
  72. data/test/worksheet/test_write_url.rb +19 -0
  73. data/test/worksheet/test_write_worksheet_attributes.rb +21 -0
  74. metadata +38 -5
  75. data/lib/write_xlsx/worksheet/print_style.rb +0 -51
  76. data/test/worksheet/test_write_worksheet.rb +0 -19
@@ -40,7 +40,7 @@ module Writexlsx
40
40
  # require 'rubygems'
41
41
  # require 'write_xlsx'
42
42
  #
43
- # workbook = WriteXLSX.new( 'chart.xlsx' )
43
+ # workbook = WriteXLSX.new('chart.xlsx')
44
44
  # worksheet = workbook.add_worksheet
45
45
  #
46
46
  # # Add the worksheet data the chart refers to.
@@ -64,12 +64,13 @@ module Writexlsx
64
64
  #
65
65
  # ==DESCRIPTION
66
66
  #
67
- # The Chart module is an abstract base class for modules that implement
67
+ # The Chart is an abstract base class for modules that implement
68
68
  # charts in WriteXLSX. The information below is applicable to all of
69
69
  # the available subclasses.
70
70
  #
71
- # The Chart module isn't used directly. A chart object is created via
72
- # the Workbook add_chart() method where the chart type is specified:
71
+ # The Chart isn't used directly. A chart object is created via
72
+ # the {WriteXLXS#add_chart()}
73
+ # method where the chart type is specified:
73
74
  #
74
75
  # chart = workbook.add_chart( :type => 'column' )
75
76
  #
@@ -99,6 +100,34 @@ module Writexlsx
99
100
  # ===radar
100
101
  # Creates a Radar style chart. See Writexlsx::Chart::Radar.
101
102
  #
103
+ # Chart subtypes are also supported in some cases:
104
+ #
105
+ # workbook.add_chart(:type => 'bar', :subtype => 'stacked')
106
+ #
107
+ # The currently available subtypes are:
108
+ #
109
+ # area
110
+ # stacked
111
+ # percent_stacked
112
+ #
113
+ # bar
114
+ # stacked
115
+ # percent_stacked
116
+ #
117
+ # column
118
+ # stacked
119
+ # percent_stacked
120
+ #
121
+ # scatter
122
+ # straight_with_markers
123
+ # straight
124
+ # smooth_with_markers
125
+ # smooth
126
+ #
127
+ # radar
128
+ # with_markers
129
+ # filled
130
+ #
102
131
  # ==CHART FORMATTING
103
132
  #
104
133
  # The following chart formatting properties can be set for any chart object
@@ -112,12 +141,14 @@ module Writexlsx
112
141
  # marker
113
142
  # trendline
114
143
  # data_labels
144
+ #
115
145
  # Chart formatting properties are generally set using hash refs.
116
146
  #
117
147
  # chart.add_series(
118
148
  # :values => '=Sheet1!$B$1:$B$5',
119
149
  # :line => { color => 'blue' }
120
150
  # )
151
+ #
121
152
  # In some cases the format properties can be nested. For example a marker
122
153
  # may contain border and fill sub-properties.
123
154
  #
@@ -131,6 +162,7 @@ module Writexlsx
131
162
  # :fill => { color => 'yellow' }
132
163
  # }
133
164
  # )
165
+ #
134
166
  # ===Line
135
167
  #
136
168
  # The line format is used to specify properties of line objects that appear
@@ -597,62 +629,81 @@ module Writexlsx
597
629
  # chart.add_series(
598
630
  # :categories => '=Sheet1!$A$2:$A$10', # Optional.
599
631
  # :values => '=Sheet1!$B$2:$B$10', # Required.
600
- # :line => { color => 'blue' }
632
+ # :line => { :color => 'blue' }
601
633
  # )
602
634
  #
603
635
  # The properties that can be set are:
604
636
  #
605
- # ====:values
606
- # This is the most important property of a series and must be set
607
- # for every chart object. It links the chart with the worksheet data
608
- # that it displays. A formula or array ref can be used for the
609
- # data range, see below.
637
+ # ===:values
638
+ # This is the most important property of a series and must be set
639
+ # for every chart object. It links the chart with the worksheet data
640
+ # that it displays. A formula or array ref can be used for the
641
+ # data range, see below.
610
642
  #
611
- # ====:categories
612
- # This sets the chart category labels. The category is more or less
613
- # the same as the X-axis. In most chart types the categories property
614
- # is optional and the chart will just assume a sequential series
615
- # from 1 .. n.
643
+ # ===:categories
644
+ # This sets the chart category labels. The category is more or less
645
+ # the same as the X-axis. In most chart types the categories property
646
+ # is optional and the chart will just assume a sequential series
647
+ # from 1 .. n.
616
648
  #
617
- # ====:name
618
- # Set the name for the series. The name is displayed in the chart
619
- # legend and in the formula bar. The name property is optional and
620
- # if it isn't supplied it will default to Series 1 .. n.
649
+ # ===:name
650
+ # Set the name for the series. The name is displayed in the chart
651
+ # legend and in the formula bar. The name property is optional and
652
+ # if it isn't supplied it will default to Series 1 .. n.
621
653
  #
622
- # ====:line
623
- # Set the properties of the series line type such as colour and
624
- # width. See the "CHART FORMATTING" section below.
654
+ # ===:line
655
+ # Set the properties of the series line type such as colour and
656
+ # width. See the "CHART FORMATTING" section below.
625
657
  #
626
- # ====:border
627
- # Set the border properties of the series such as colour and style.
628
- # See the "CHART FORMATTING" section below.
658
+ # ===:border
659
+ # Set the border properties of the series such as colour and style.
660
+ # See the "CHART FORMATTING" section below.
629
661
  #
630
- # ====:fill
631
- # Set the fill properties of the series such as colour. See the
632
- # "CHART FORMATTING" section below.
662
+ # ===:fill
663
+ # Set the fill properties of the series such as colour. See the
664
+ # "CHART FORMATTING"
665
+ # section below.
633
666
  #
634
- # ====:marker
635
- # Set the properties of the series marker such as style and color.
636
- # See the "CHART FORMATTING" section below.
667
+ # ==:marker
668
+ # Set the properties of the series marker such as style and color.
669
+ # See the "CHART FORMATTING" section below.
637
670
  #
638
- # ====:trendline
639
- # Set the properties of the series trendline such as linear,
640
- # polynomial and moving average types. See the "CHART FORMATTING"
641
- # section below.
671
+ # ===:trendline
672
+ # Set the properties of the series trendline such as linear,
673
+ # polynomial and moving average types. See the "CHART FORMATTING"
674
+ # section below.
642
675
  #
643
- # ====:data_labels
644
- # Set data labels for the series. See the "CHART FORMATTING"
645
- # section below.
676
+ # ===:data_labels
677
+ # Set data labels for the series. See the "CHART FORMATTING"
678
+ # section below.
679
+ #
680
+ # ===:invert_if_negative
681
+ # Invert the fill colour for negative values. Usually only applicable
682
+ # to column and bar charts.
683
+ #
684
+ # ===:overlap
685
+ # Set the overlap between series in a Bar/Column chart. The range is
686
+ # <tt>+/- 100</tt>. Default is 0.
687
+ #
688
+ # :overlap => 20
689
+ #
690
+ # Note, it is only necessary to apply this property to one series of the chart.
691
+ #
692
+ # ===:gap
693
+ # Set the gap between series in a Bar/Column chart. The range is
694
+ # <tt>0 to 500</tt>. Default is 150.
646
695
  #
647
- # ====:invert_if_negative
648
- # Invert the fill colour for negative values. Usually only applicable
649
- # to column and bar charts.
696
+ # :gap => 200,
697
+ #
698
+ # Note, it is only necessary to apply this property to one series of the
699
+ # chart.
650
700
  #
651
701
  # The categories and values can take either a range formula such
652
- # as =Sheet1!$A$2:$A$7 or, more usefully when generating the range
702
+ # as <tt>=Sheet1!$A$2:$A$7</tt> or, more usefully when generating the range
653
703
  # programmatically, an array ref with zero indexed row/column values:
654
704
  #
655
705
  # [ sheetname, row_start, row_end, col_start, col_end ]
706
+ #
656
707
  # The following are equivalent:
657
708
  #
658
709
  # chart.add_series( categories => '=Sheet1!$A$2:$A$7' ) # Same as ...
@@ -677,6 +728,359 @@ module Writexlsx
677
728
  # :name => 'Test data series 2'
678
729
  # )
679
730
  #
731
+ # ==SERIES OPTIONS
732
+ #
733
+ # This section details the following properties of add_series() in more
734
+ # detail:
735
+ #
736
+ # marker
737
+ # trendline
738
+ # y_error_bars
739
+ # x_error_bars
740
+ # data_labels
741
+ # points
742
+ #
743
+ # ===Marker
744
+ #
745
+ # The marker format specifies the properties of the markers used to
746
+ # distinguish series on a chart. In general only Line and Scatter chart
747
+ # types and trendlines use markers.
748
+ #
749
+ # The following properties can be set for marker formats in a chart.
750
+ #
751
+ # type
752
+ # size
753
+ # border
754
+ # fill
755
+ #
756
+ # The type property sets the type of marker that is used with a series.
757
+ #
758
+ # chart.add_series(
759
+ # :values => '=Sheet1!$B$1:$B$5',
760
+ # :marker => { :type => 'diamond' }
761
+ # )
762
+ #
763
+ # The following type properties can be set for marker formats in a chart.
764
+ # These are shown in the same order as in the Excel format dialog.
765
+ #
766
+ # automatic
767
+ # none
768
+ # square
769
+ # diamond
770
+ # triangle
771
+ # x
772
+ # star
773
+ # short_dash
774
+ # long_dash
775
+ # circle
776
+ # plus
777
+ #
778
+ # The automatic type is a special case which turns on a marker using the
779
+ # default marker style for the particular series number.
780
+ #
781
+ # chart.add_series(
782
+ # :values => '=Sheet1!$B$1:$B$5',
783
+ # :marker => { :type => 'automatic' }
784
+ # )
785
+ #
786
+ # If automatic is on then other marker properties such as size, border or
787
+ # fill cannot be set.
788
+ #
789
+ # The size property sets the size of the marker and is generally used in
790
+ # conjunction with type.
791
+ #
792
+ # chart.add_series(
793
+ # :values => '=Sheet1!$B$1:$B$5',
794
+ # :marker => { :type => 'diamond', :size => 7 }
795
+ # )
796
+ #
797
+ # Nested border and fill properties can also be set for a marker. See the
798
+ # "CHART FORMATTING"
799
+ # section below.
800
+ #
801
+ # chart.add_series(
802
+ # :values => '=Sheet1!$B$1:$B$5',
803
+ # :marker => {
804
+ # :type => 'square',
805
+ # :size => 5,
806
+ # :border => { :color => 'red' },
807
+ # :fill => { :color => 'yellow' }
808
+ # }
809
+ # )
810
+ #
811
+ # ===Trendline
812
+ #
813
+ # A trendline can be added to a chart series to indicate trends in the data
814
+ # such as a moving average or a polynomial fit.
815
+ #
816
+ # The following properties can be set for trendlines in a chart series.
817
+ #
818
+ # type
819
+ # order (for polynomial trends)
820
+ # period (for moving average)
821
+ # forward (for all except moving average)
822
+ # backward (for all except moving average)
823
+ # name
824
+ # line
825
+ #
826
+ # The type property sets the type of trendline in the series.
827
+ #
828
+ # chart.add_series(
829
+ # :values => '=Sheet1!$B$1:$B$5',
830
+ # :trendline => { :type => 'linear' }
831
+ # )
832
+ #
833
+ # The available trendline types are:
834
+ #
835
+ # exponential
836
+ # linear
837
+ # log
838
+ # moving_average
839
+ # polynomial
840
+ # power
841
+ #
842
+ # A polynomial trendline can also specify the order of the polynomial.
843
+ # The default value is 2.
844
+ #
845
+ # chart.add_series(
846
+ # :values => '=Sheet1!$B$1:$B$5',
847
+ # :trendline => {
848
+ # :type => 'polynomial',
849
+ # :order => 3
850
+ # }
851
+ # )
852
+ #
853
+ # A moving_average trendline can also specify the period of the moving
854
+ # average. The default value is 2.
855
+ #
856
+ # chart.add_series(
857
+ # :values => '=Sheet1!$B$1:$B$5',
858
+ # :trendline => {
859
+ # :type => 'moving_average',
860
+ # :period => 3,
861
+ # }
862
+ # )
863
+ #
864
+ # The forward and backward properties set the forecast period of the
865
+ # trendline.
866
+ #
867
+ # chart.add_series(
868
+ # :values => '=Sheet1!$B$1:$B$5',
869
+ # :trendline => {
870
+ # :type => 'linear',
871
+ # :forward => 0.5,
872
+ # :backward => 0.5
873
+ # }
874
+ # )
875
+ #
876
+ # The name property sets an optional name for the trendline that will
877
+ # appear in the chart legend. If it isn't specified the Excel default
878
+ # name will be displayed. This is usually a combination of the
879
+ # trendline type and the series name.
880
+ #
881
+ # chart.add_series(
882
+ # :values => '=Sheet1!$B$1:$B$5',
883
+ # :trendline => {
884
+ # :type => 'linear',
885
+ # :name => 'Interpolated trend'
886
+ # }
887
+ # )
888
+ #
889
+ # Several of these properties can be set in one go:
890
+ #
891
+ # chart.add_series(
892
+ # :values => '=Sheet1!$B$1:$B$5',
893
+ # :trendline => {
894
+ # :type => 'linear',
895
+ # :name => 'My trend name',
896
+ # :forward => 0.5,
897
+ # :backward => 0.5,
898
+ # :line => {
899
+ # :color => 'red',
900
+ # :width => 1,
901
+ # :dash_type => 'long_dash'
902
+ # }
903
+ # }
904
+ # )
905
+ #
906
+ # Trendlines cannot be added to series in a stacked chart or pie chart,
907
+ # radar chart or (when implemented) to 3D, surface, or doughnut charts.
908
+ #
909
+ # ===Error Bars
910
+ #
911
+ # Error bars can be added to a chart series to indicate error bounds in the
912
+ # data. The error bars can be vertical y_error_bars (the most common type)
913
+ # or horizontal x_error_bars (for Bar and Scatter charts only).
914
+ #
915
+ # The following properties can be set for error bars in a chart series.
916
+ #
917
+ # type
918
+ # value (for all types except standard error)
919
+ # direction
920
+ # end_style
921
+ # line
922
+ #
923
+ # The type property sets the type of error bars in the series.
924
+ #
925
+ # chart.add_series(
926
+ # :values => '=Sheet1!$B$1:$B$5',
927
+ # :y_error_bars => { :type => 'standard_error' }
928
+ # )
929
+ #
930
+ # The available error bars types are available:
931
+ #
932
+ # fixed
933
+ # percentage
934
+ # standard_deviation
935
+ # standard_error
936
+ #
937
+ # Note, the "custom" error bars type is not supported.
938
+ #
939
+ # All error bar types, except for standard_error must also have a value
940
+ # associated with it for the error bounds:
941
+ #
942
+ # chart.add_series(
943
+ # :values => '=Sheet1!$B$1:$B$5',
944
+ # :y_error_bars => {
945
+ # :type => 'percentage',
946
+ # :value => 5
947
+ # }
948
+ # )
949
+ #
950
+ # The direction property sets the direction of the error bars. It should
951
+ # be one of the following:
952
+ #
953
+ # plus # Positive direction only.
954
+ # minus # Negative direction only.
955
+ # both # Plus and minus directions, The default.
956
+ #
957
+ # The end_style property sets the style of the error bar end cap. The
958
+ # options are 1 (the default) or 0 (for no end cap):
959
+ #
960
+ # chart.add_series(
961
+ # :values => '=Sheet1!$B$1:$B$5',
962
+ # :y_error_bars => {
963
+ # :type => 'fixed',
964
+ # :value => 2,
965
+ # :end_style => 0,
966
+ # :direction => 'minus'
967
+ # }
968
+ # )
969
+ #
970
+ # ===Data Labels
971
+ #
972
+ # Data labels can be added to a chart series to indicate the values of the
973
+ # plotted data points.
974
+ #
975
+ # The following properties can be set for data_labels formats in a chart.
976
+ #
977
+ # value
978
+ # category
979
+ # series_name
980
+ # position
981
+ # leader_lines
982
+ # percentage
983
+ #
984
+ # The value property turns on the Value data label for a series.
985
+ #
986
+ # chart.add_series(
987
+ # :values => '=Sheet1!$B$1:$B$5',
988
+ # :data_labels => { :value => 1 }
989
+ # )
990
+ # The category property turns on the Category Name data label for a series.
991
+ #
992
+ # chart.add_series(
993
+ # :values => '=Sheet1!$B$1:$B$5',
994
+ # :data_labels => { :category => 1 }
995
+ # )
996
+ #
997
+ # The series_name property turns on the Series Name data label for a series.
998
+ #
999
+ # chart.add_series(
1000
+ # :values => '=Sheet1!$B$1:$B$5',
1001
+ # :data_labels => { :series_name => 1 }
1002
+ # )
1003
+ #
1004
+ # The position property is used to position the data label for a series.
1005
+ #
1006
+ # chart.add_series(
1007
+ # :values => '=Sheet1!$B$1:$B$5',
1008
+ # :data_labels => { :value => 1, :position => 'center' },
1009
+ # )
1010
+ #
1011
+ # Valid positions are:
1012
+ #
1013
+ # center
1014
+ # right
1015
+ # left
1016
+ # top
1017
+ # bottom
1018
+ # above # Same as top
1019
+ # below # Same as bottom
1020
+ # inside_end # Pie chart mainly.
1021
+ # outside_end # Pie chart mainly.
1022
+ # best_fit # Pie chart mainly.
1023
+ #
1024
+ # The percentage property is used to turn on the display of data labels as
1025
+ # a Percentage for a series. It is mainly used for pie charts.
1026
+ #
1027
+ # chart.add_series(
1028
+ # :values => '=Sheet1!$B$1:$B$5',
1029
+ # :data_labels => { :percentage => 1 }
1030
+ # )
1031
+ #
1032
+ # The leader_lines property is used to turn on Leader Lines for the data
1033
+ # label for a series. It is mainly used for pie charts.
1034
+ #
1035
+ # chart.add_series(
1036
+ # :values => '=Sheet1!$B$1:$B$5',
1037
+ # :data_labels => { :value => 1, :leader_lines => 1 }
1038
+ # )
1039
+ #
1040
+ # Note: Even when leader lines are turned on they aren't automatically
1041
+ # visible in Excel or Excel::Writer::XLSX. Due to an Excel limitation
1042
+ # (or design) leader lines only appear if the data label is moved
1043
+ # manually or if the data labels are very close and need to be adjusted
1044
+ # automatically.
1045
+ #
1046
+ # ===Points
1047
+ #
1048
+ # In general formatting is applied to an entire series in a chart. However,
1049
+ # it is occasionally required to format individual points in a series. In
1050
+ # particular this is required for Pie charts where each segment is
1051
+ # represented by a point.
1052
+ #
1053
+ # In these cases it is possible to use the points property of add_series():
1054
+ #
1055
+ # chart.add_series(
1056
+ # :values => '=Sheet1!$A$1:$A$3',
1057
+ # :points => [
1058
+ # { :fill => { :color => '#FF0000' } },
1059
+ # { :fill => { ?color => '#CC0000' } },
1060
+ # { :fill => { :color => '#990000' } }
1061
+ # ]
1062
+ # )
1063
+ #
1064
+ # The points property takes an array ref of format options (see the
1065
+ # "CHART FORMATTING"
1066
+ # section below). To assign default properties to points in a series pass
1067
+ # nil values in the array ref:
1068
+ #
1069
+ # # Format point 3 of 3 only.
1070
+ # chart.add_series(
1071
+ # :values => '=Sheet1!$A$1:$A$3',
1072
+ # :points => [
1073
+ # nil,
1074
+ # nil,
1075
+ # { :fill => { :color => '#990000' } }
1076
+ # ]
1077
+ # )
1078
+ #
1079
+ # # Format the first point only.
1080
+ # chart.add_series(
1081
+ # :values => '=Sheet1!$A$1:$A$3',
1082
+ # :points => [ { :fill => { :color => '#FF0000' } } ]
1083
+ # )
680
1084
  def add_series(params)
681
1085
  # Check that the required input has been specified.
682
1086
  unless params.has_key?(:values)
@@ -727,6 +1131,16 @@ module Writexlsx
727
1131
  # Set the "invert if negative" fill property.
728
1132
  invert_if_neg = params[:invert_if_negative]
729
1133
 
1134
+ # Set the gap for Bar/Column charts.
1135
+ if params[:gap]
1136
+ @series_gap = params[:gap]
1137
+ end
1138
+
1139
+ # Set the overlap for Bar/Column charts.
1140
+ if params[:overlap]
1141
+ @series_overlap = params[:overlap]
1142
+ end
1143
+
730
1144
  # Set the secondary axis properties.
731
1145
  x2_axis = params[:x2_axis]
732
1146
  y2_axis = params[:y2_axis]
@@ -854,6 +1268,93 @@ module Writexlsx
854
1268
  # :max => 80
855
1269
  # )
856
1270
  #
1271
+ # ==CHART FONTS
1272
+ #
1273
+ # The following font properties can be set for any chart object that they
1274
+ # apply to (and that are supported by WriteXLSX) such as chart titles,
1275
+ # axis labels and axis numbering. They correspond to the equivalent
1276
+ # Worksheet cell Format object properties. See "FORMAT_METHODS" for more
1277
+ # information.
1278
+ #
1279
+ # name
1280
+ # size
1281
+ # bold
1282
+ # italic
1283
+ # underline
1284
+ # color
1285
+ #
1286
+ # The following explains the available font properties:
1287
+ #
1288
+ # ===name
1289
+ # Set the font name:
1290
+ #
1291
+ # chart.set_x_axis( :num_font => { :name => 'Arial' } )
1292
+ #
1293
+ # ===size
1294
+ # Set the font size:
1295
+ #
1296
+ # chart.set_x_axis( :num_font => { :name => 'Arial', :size => 10 } )
1297
+ #
1298
+ # ===bold
1299
+ # Set the font bold property, should be 0 or 1:
1300
+ #
1301
+ # chart.set_x_axis( :num_font => { :bold => 1 } )
1302
+ #
1303
+ # ===italic
1304
+ # Set the font italic property, should be 0 or 1:
1305
+ #
1306
+ # chart.set_x_axis( :num_font => { :italic => 1 } )
1307
+ #
1308
+ # ===underline
1309
+ # Set the font underline property, should be 0 or 1:
1310
+ #
1311
+ # chart.set_x_axis( :num_font => { :underline => 1 } )
1312
+ #
1313
+ # ===color
1314
+ # Set the font color property. Can be a color index, a color name or HTML
1315
+ # style RGB colour:
1316
+ #
1317
+ # chart.set_x_axis( :num_font => { :color => 'red' } )
1318
+ # chart.set_y_axis( :num_font => { :color => '#92D050' } )
1319
+ #
1320
+ # Here is an example of Font formatting in a Chart program:
1321
+ #
1322
+ # # Format the chart title.
1323
+ # chart.set_title(
1324
+ # :name => 'Sales Results Chart',
1325
+ # :name_font => {
1326
+ # :name => 'Calibri',
1327
+ # :color => 'yellow'
1328
+ # }
1329
+ # )
1330
+ #
1331
+ # # Format the X-axis.
1332
+ # chart.set_x_axis(
1333
+ # :name => 'Month',
1334
+ # :name_font => {
1335
+ # :name => 'Arial',
1336
+ # :color => '#92D050'
1337
+ # },
1338
+ # :num_font => {
1339
+ # :name => 'Courier New',
1340
+ # :color => '#00B0F0'
1341
+ # }
1342
+ # )
1343
+ #
1344
+ # # Format the Y-axis.
1345
+ # chart.set_y_axis(
1346
+ # :name => 'Sales (1000 units)',
1347
+ # :name_font => {
1348
+ # :name => 'Century',
1349
+ # :underline => 1,
1350
+ # :color => 'red'
1351
+ # },
1352
+ # :num_font => {
1353
+ # :bold => 1,
1354
+ # :italic => 1,
1355
+ # :color => '#7030A0'
1356
+ # }
1357
+ # )
857
1358
  def set_x_axis(params = {})
858
1359
  @x_axis.merge_with_hash(self, params)
859
1360
  end
@@ -888,13 +1389,17 @@ module Writexlsx
888
1389
  # The set_title() method is used to set properties of the chart title.
889
1390
  #
890
1391
  # chart.set_title( :name => 'Year End Results' )
1392
+ #
891
1393
  # The properties that can be set are:
892
1394
  #
893
- # ====:name
1395
+ # ===:name
894
1396
  # Set the name (title) for the chart. The name is displayed above the
895
- # chart. The name can also be a formula such as =Sheet1!$A$1. The name
1397
+ # chart. The name can also be a formula such as +=Sheet1!$A$1+. The name
896
1398
  # property is optional. The default is to have no chart title.
897
1399
  #
1400
+ # ===:name_font
1401
+ # Set the font properties for the chart title. See the "CHART FONTS" section.
1402
+ #
898
1403
  def set_title(params)
899
1404
  name, name_formula = process_names(params[:name], params[:name_formula])
900
1405
  data_id = get_data_id(name_formula, params[:data])
@@ -913,12 +1418,14 @@ module Writexlsx
913
1418
  # The set_legend() method is used to set properties of the chart legend.
914
1419
  #
915
1420
  # chart.set_legend( :position => 'none' )
1421
+ #
916
1422
  # The properties that can be set are:
917
1423
  #
918
- # ====:position
1424
+ # ===:position
919
1425
  # Set the position of the chart legend.
920
1426
  #
921
1427
  # chart.set_legend( :position => 'bottom' )
1428
+ #
922
1429
  # The default legend position is right. The available positions are:
923
1430
  #
924
1431
  # none
@@ -928,13 +1435,15 @@ module Writexlsx
928
1435
  # right
929
1436
  # overlay_left
930
1437
  # overlay_right
931
- # ====:delete_series
1438
+ #
1439
+ # ===:delete_series
1440
+ #
932
1441
  # This allows you to remove 1 or more series from the the legend
933
1442
  # (the series will still display on the chart). This property takes
934
1443
  # an array ref as an argument and the series are zero indexed:
935
1444
  #
936
1445
  # # Delete/hide series index 0 and 2 from the legend.
937
- # chart.set_legend( :delete_series => [0, 2] )
1446
+ # chart.set_legend(:delete_series => [0, 2])
938
1447
  #
939
1448
  def set_legend(params)
940
1449
  @legend_position = params[:position] || 'right'
@@ -962,9 +1471,18 @@ module Writexlsx
962
1471
  # The set_chartarea() method is used to set the properties of the chart
963
1472
  # area.
964
1473
  #
965
- # This method isn't implemented yet and is only available in
966
- # writeexcel gem. However, it can be simulated using the
967
- # set_style() method.
1474
+ # chart.set_chartarea(
1475
+ # :border => { :none => 1 },
1476
+ # :fill => { :color => 'red' }
1477
+ # )
1478
+ #
1479
+ # The properties that can be set are:
1480
+ # ===:border
1481
+ # Set the border properties of the chartarea such as colour and style.
1482
+ # See the "CHART FORMATTING" section.
1483
+ # ===:fill
1484
+ # Set the fill properties of the plotarea such as colour. See the
1485
+ # "CHART FORMATTING" section.
968
1486
  #
969
1487
  def set_chartarea(params)
970
1488
  # Convert the user defined properties to internal properties.
@@ -979,6 +1497,8 @@ module Writexlsx
979
1497
  #
980
1498
  # chart.set_style( 4 )
981
1499
  #
1500
+ # The default style is 2.
1501
+ #
982
1502
  def set_style(style_id = 2)
983
1503
  style_id = 2 if style_id < 0 || style_id > 42
984
1504
  @style_id = style_id
@@ -1017,6 +1537,35 @@ module Writexlsx
1017
1537
  #
1018
1538
  # Set dimensions for scale for the chart.
1019
1539
  #
1540
+ # The set_size() method is used to set the dimensions of the chart.
1541
+ # The size properties that can be set are:
1542
+ #
1543
+ # width
1544
+ # height
1545
+ # x_scale
1546
+ # y_scale
1547
+ # x_offset
1548
+ # y_offset
1549
+ #
1550
+ # The width and height are in pixels. The default chart width is 480
1551
+ # pixels and the default height is 288 pixels. The size of the chart can
1552
+ # be modified by setting the width and height or by setting the :x_scale
1553
+ # and :y_scale:
1554
+ #
1555
+ # chart.set_size( :width => 720, :height => 576 )
1556
+ #
1557
+ # # Same as:
1558
+ #
1559
+ # chart.set_size( :x_scale => 1.5, :y_scale => 2 )
1560
+ #
1561
+ # The :x_offset and :y_offset position the top left corner of the chart
1562
+ # in the cell that it is inserted into.
1563
+ #
1564
+ # Note: the :x_scale, :y_scale, :x_offset and :y_offset parameters can also
1565
+ # be set via the insert_chart() method:
1566
+ #
1567
+ # worksheet.insert_chart( 'E2', chart, 2, 4, 1.5, 2 )
1568
+ #
1020
1569
  def set_size(params = {})
1021
1570
  @width = params[:width] if params[:width]
1022
1571
  @height = params[:height] if params[:height]
@@ -1051,6 +1600,20 @@ module Writexlsx
1051
1600
  #
1052
1601
  # Set properties for the chart up-down bars.
1053
1602
  #
1603
+ # The set_up_down_bars() method adds Up-Down bars to Line charts to
1604
+ # indicate the difference between the first and last data series.
1605
+ #
1606
+ # chart.set_up_down_bars
1607
+ # It is possible to format the up and down bars to add fill and border
1608
+ # properties if required. See the "CHART FORMATTING" section below.
1609
+ #
1610
+ # chart.set_up_down_bars(
1611
+ # :up => { :fill => { :color => 'green' } },
1612
+ # :down => { :fill => { :color => 'red' } }
1613
+ # )
1614
+ # Up-down bars can only be applied to Line charts and to Stock charts
1615
+ # (by default).
1616
+ #
1054
1617
  def set_up_down_bars(params = {})
1055
1618
  # Map border to line.
1056
1619
  [:up, :down].each do |up_down|
@@ -1077,6 +1640,18 @@ module Writexlsx
1077
1640
  #
1078
1641
  # Set properties for the chart drop lines.
1079
1642
  #
1643
+ # The set_drop_lines() method adds Drop Lines to charts to show the
1644
+ # Category value of points in the data.
1645
+ #
1646
+ # chart.set_drop_lines
1647
+ #
1648
+ # It is possible to format the Drop Line line properties if required.
1649
+ # See the "CHART FORMATTING" section below.
1650
+ #
1651
+ # chart.set_drop_lines(:line => { :color => 'red', :dash_type => 'square_dot' } )
1652
+ #
1653
+ # Drop Lines are only available in Line, Area and Stock charts.
1654
+ #
1080
1655
  def set_drop_lines(params = {})
1081
1656
  # Set the drop line properties.
1082
1657
  line = line_properties(params[:line])
@@ -1087,6 +1662,18 @@ module Writexlsx
1087
1662
  #
1088
1663
  # Set properties for the chart high-low lines.
1089
1664
  #
1665
+ # The set_high_low_lines() method adds High-Low lines to charts to show
1666
+ # the maximum and minimum values of points in a Category.
1667
+ #
1668
+ # chart.set_high_low_lines
1669
+ #
1670
+ # It is possible to format the High-Low Line line properties if required.
1671
+ # See the "CHART FORMATTING" section below.
1672
+ #
1673
+ # chart.set_high_low_lines( :line => { :color => 'red' } )
1674
+ #
1675
+ # High-Low Lines are only available in Line and Stock charts.
1676
+ #
1090
1677
  def set_high_low_lines(params = {})
1091
1678
  # Set the drop line properties.
1092
1679
  line = line_properties(params[:line])
@@ -1115,6 +1702,11 @@ module Writexlsx
1115
1702
  subtype = @subtype
1116
1703
  subtype = 'percentStacked' if subtype == 'percent_stacked'
1117
1704
 
1705
+ # Set a default overlap for stacked charts.
1706
+ if @subtype =~ /stacked/
1707
+ @series_overlap = 100 unless @series_overlap
1708
+ end
1709
+
1118
1710
  @writer.tag_elements('c:barChart') do
1119
1711
  # Write the c:barDir element.
1120
1712
  write_bar_dir
@@ -1126,8 +1718,11 @@ module Writexlsx
1126
1718
  # write the c:marker element.
1127
1719
  write_marker_value
1128
1720
 
1721
+ # Write the c:gapWidth element.
1722
+ write_gap_width(@series_gap)
1723
+
1129
1724
  # write the c:overlap element.
1130
- write_overlap if @subtype =~ /stacked/
1725
+ write_overlap(@series_overlap)
1131
1726
 
1132
1727
  # Write the c:axId elements
1133
1728
  write_axis_ids(params)
@@ -1842,6 +2437,7 @@ module Writexlsx
1842
2437
  #
1843
2438
  # Write the <c:plotArea> element.
1844
2439
  #
2440
+
1845
2441
  def write_plot_area # :nodoc:
1846
2442
  write_plot_area_base
1847
2443
  end
@@ -3192,8 +3788,10 @@ module Writexlsx
3192
3788
  #
3193
3789
  # Write the <c:overlap> element.
3194
3790
  #
3195
- def write_overlap # :nodoc:
3196
- @writer.empty_tag('c:overlap', ['val', 100])
3791
+ def write_overlap(val = nil) # :nodoc:
3792
+ return unless val
3793
+
3794
+ @writer.empty_tag('c:overlap', ['val', val])
3197
3795
  end
3198
3796
 
3199
3797
  #
@@ -3502,7 +4100,7 @@ module Writexlsx
3502
4100
 
3503
4101
  @writer.tag_elements('c:upDownBars') do
3504
4102
  # Write the c:gapWidth element.
3505
- write_gap_width
4103
+ write_gap_width(150)
3506
4104
 
3507
4105
  # Write the c:upBars element.
3508
4106
  write_up_bars(@up_down_bars[:_up])
@@ -3515,8 +4113,10 @@ module Writexlsx
3515
4113
  #
3516
4114
  # Write the <c:gapWidth> element.
3517
4115
  #
3518
- def write_gap_width
3519
- @writer.empty_tag('c:gapWidth', ['val', 150])
4116
+ def write_gap_width(val = nil)
4117
+ return unless val
4118
+
4119
+ @writer.empty_tag('c:gapWidth', ['val', val])
3520
4120
  end
3521
4121
 
3522
4122
  #