writeexcel 0.5.0 → 0.6.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (130) hide show
  1. data/.gitattributes +1 -1
  2. data/.gitignore +24 -24
  3. data/README.rdoc +34 -55
  4. data/VERSION +1 -1
  5. data/charts/chartex.rb +316 -316
  6. data/charts/demo1.rb +46 -46
  7. data/charts/demo2.rb +65 -65
  8. data/charts/demo3.rb +117 -117
  9. data/charts/demo4.rb +119 -119
  10. data/charts/demo5.rb +48 -48
  11. data/examples/a_simple.rb +43 -43
  12. data/examples/autofilter.rb +265 -265
  13. data/examples/bigfile.rb +30 -30
  14. data/examples/chart_area.rb +121 -121
  15. data/examples/chart_bar.rb +120 -120
  16. data/examples/chart_column.rb +120 -120
  17. data/examples/chart_line.rb +120 -120
  18. data/examples/chart_pie.rb +108 -108
  19. data/examples/chart_scatter.rb +121 -121
  20. data/examples/chart_stock.rb +148 -148
  21. data/examples/chess.rb +142 -142
  22. data/examples/colors.rb +129 -129
  23. data/examples/comments1.rb +27 -27
  24. data/examples/comments2.rb +352 -352
  25. data/examples/copyformat.rb +52 -52
  26. data/examples/data_validate.rb +279 -279
  27. data/examples/date_time.rb +87 -87
  28. data/examples/defined_name.rb +32 -32
  29. data/examples/demo.rb +124 -124
  30. data/examples/diag_border.rb +36 -36
  31. data/examples/formats.rb +490 -490
  32. data/examples/formula_result.rb +30 -30
  33. data/examples/header.rb +137 -137
  34. data/examples/hide_sheet.rb +29 -29
  35. data/examples/hyperlink.rb +43 -43
  36. data/examples/images.rb +63 -63
  37. data/examples/indent.rb +31 -31
  38. data/examples/merge1.rb +40 -40
  39. data/examples/merge2.rb +45 -45
  40. data/examples/merge3.rb +66 -66
  41. data/examples/merge4.rb +83 -83
  42. data/examples/merge5.rb +80 -80
  43. data/examples/merge6.rb +67 -67
  44. data/examples/outline.rb +255 -255
  45. data/examples/outline_collapsed.rb +209 -209
  46. data/examples/panes.rb +113 -113
  47. data/examples/properties.rb +34 -34
  48. data/examples/properties_jp.rb +33 -33
  49. data/examples/protection.rb +47 -47
  50. data/examples/regions.rb +53 -53
  51. data/examples/repeat.rb +43 -43
  52. data/examples/right_to_left.rb +27 -27
  53. data/examples/row_wrap.rb +53 -53
  54. data/examples/stats.rb +74 -74
  55. data/examples/stocks.rb +81 -81
  56. data/examples/tab_colors.rb +31 -31
  57. data/examples/utf8.rb +15 -15
  58. data/examples/write_arrays.rb +83 -83
  59. data/lib/writeexcel/biffwriter.rb +232 -232
  60. data/lib/writeexcel/caller_info.rb +12 -12
  61. data/lib/writeexcel/chart.rb +2190 -2177
  62. data/lib/writeexcel/charts/area.rb +154 -154
  63. data/lib/writeexcel/charts/bar.rb +177 -177
  64. data/lib/writeexcel/charts/column.rb +156 -156
  65. data/lib/writeexcel/charts/external.rb +66 -66
  66. data/lib/writeexcel/charts/line.rb +154 -154
  67. data/lib/writeexcel/charts/pie.rb +169 -169
  68. data/lib/writeexcel/charts/scatter.rb +192 -192
  69. data/lib/writeexcel/charts/stock.rb +213 -213
  70. data/lib/writeexcel/colors.rb +64 -64
  71. data/lib/writeexcel/compatibility.rb +0 -255
  72. data/lib/writeexcel/debug_info.rb +37 -33
  73. data/lib/writeexcel/excelformulaparser.rb +587 -587
  74. data/lib/writeexcel/format.rb +13 -4
  75. data/lib/writeexcel/formula.rb +26 -9
  76. data/lib/writeexcel/helper.rb +68 -64
  77. data/lib/writeexcel/olewriter.rb +311 -311
  78. data/lib/writeexcel/properties.rb +242 -240
  79. data/lib/writeexcel/storage_lite.rb +984 -978
  80. data/lib/writeexcel/workbook.rb +3210 -3192
  81. data/lib/writeexcel/worksheet.rb +143 -51
  82. data/lib/writeexcel/write_file.rb +44 -40
  83. data/lib/writeexcel.rb +1159 -1159
  84. data/test/helper.rb +31 -28
  85. data/test/perl_output/README +31 -31
  86. data/test/test_00_IEEE_double.rb +13 -13
  87. data/test/test_01_add_worksheet.rb +10 -10
  88. data/test/test_02_merge_formats.rb +53 -53
  89. data/test/test_04_dimensions.rb +392 -392
  90. data/test/test_05_rows.rb +179 -179
  91. data/test/test_06_extsst.rb +77 -77
  92. data/test/test_11_date_time.rb +479 -479
  93. data/test/test_12_date_only.rb +501 -501
  94. data/test/test_13_date_seconds.rb +481 -481
  95. data/test/test_21_escher.rb +637 -637
  96. data/test/test_22_mso_drawing_group.rb +745 -745
  97. data/test/test_23_note.rb +73 -73
  98. data/test/test_24_txo.rb +75 -75
  99. data/test/test_25_position_object.rb +84 -84
  100. data/test/test_26_autofilter.rb +314 -314
  101. data/test/test_27_autofilter.rb +131 -131
  102. data/test/test_28_autofilter.rb +161 -161
  103. data/test/test_29_process_jpg.rb +683 -683
  104. data/test/test_30_validation_dval.rb +77 -77
  105. data/test/test_31_validation_dv_strings.rb +126 -126
  106. data/test/test_32_validation_dv_formula.rb +206 -206
  107. data/test/test_40_property_types.rb +188 -188
  108. data/test/test_41_properties.rb +235 -235
  109. data/test/test_42_set_properties.rb +437 -437
  110. data/test/test_50_name_stored.rb +299 -299
  111. data/test/test_51_name_print_area.rb +357 -357
  112. data/test/test_52_name_print_titles.rb +454 -454
  113. data/test/test_53_autofilter.rb +203 -203
  114. data/test/test_60_chart_generic.rb +578 -578
  115. data/test/test_61_chart_subclasses.rb +95 -95
  116. data/test/test_62_chart_formats.rb +272 -272
  117. data/test/test_63_chart_area_formats.rb +649 -649
  118. data/test/test_biff.rb +75 -75
  119. data/test/test_compatibility.rb +12 -627
  120. data/test/test_example_match.rb +3144 -3144
  121. data/test/test_formula.rb +61 -61
  122. data/test/test_ole.rb +106 -106
  123. data/test/test_storage_lite.rb +125 -125
  124. data/test/test_workbook.rb +139 -139
  125. data/test/test_worksheet.rb +110 -110
  126. data/utils/add_magic_comment.rb +80 -80
  127. data/writeexcel.gemspec +4 -6
  128. data/writeexcel.rdoc +58 -15
  129. metadata +9 -6
  130. data/test/test_new_encoding.rb +0 -205
data/lib/writeexcel.rb CHANGED
@@ -1,1159 +1,1159 @@
1
- # -*- coding: utf-8 -*-
2
- ###############################################################################
3
- #
4
- # WriteExcel.
5
- #
6
- # WriteExcel - Write to a cross-platform Excel binary file.
7
- #
8
- # Copyright 2000-2010, John McNamara, jmcnamara@cpan.org
9
- #
10
- # original written in Perl by John McNamara
11
- # converted to Ruby by Hideo Nakamura, cxn03651@msj.biglobe.ne.jp
12
- #
13
- require 'writeexcel/biffwriter'
14
- require 'writeexcel/olewriter'
15
- require 'writeexcel/formula'
16
- require 'writeexcel/format'
17
- require 'writeexcel/worksheet'
18
- require "writeexcel/workbook"
19
- require 'writeexcel/chart'
20
- require 'writeexcel/charts/area'
21
- require 'writeexcel/charts/bar'
22
- require 'writeexcel/charts/column'
23
- require 'writeexcel/charts/external'
24
- require 'writeexcel/charts/line'
25
- require 'writeexcel/charts/pie'
26
- require 'writeexcel/charts/scatter'
27
- require 'writeexcel/charts/stock'
28
- require 'writeexcel/storage_lite'
29
- require 'writeexcel/compatibility'
30
- require 'writeexcel/debug_info'
31
- #
32
- # = WriteExcel - Write to a cross-platform Excel binary file.
33
- #
34
- # == Contents
35
- # SYSNOPSYS
36
- # DESCRIPTION
37
- # QUICK START
38
- # WORKBOOK METHODS
39
- # WORKSHEET METHODS
40
- # PAGE SET-UP METHODS
41
- # CELL FORMATTING
42
- # FORMAT METHODS
43
- # COLOURS IN EXCEL
44
- # DATE AND TIME IN EXCEL
45
- # OUTLINES AND GROUPING IN EXCEL
46
- # DATA VALIDATION IN EXCEL
47
- # FORMULAS AND FUNCTIONS IN EXCEL
48
- # CHART
49
- #
50
- # == Synopsis
51
- #
52
- # To write a string, a formatted string, a number and a formula to the first
53
- # worksheet in an Excel workbook called ruby.xls:
54
- #
55
- # require 'WriteExcel'
56
- #
57
- # # Create a new Excel workbook
58
- # workbook = WriteExcel.new('ruby.xls')
59
- #
60
- # # Add a worksheet
61
- # worksheet = workbook.add_worksheet
62
- #
63
- # # Add and define a format
64
- # format = workbook.add_format # Add a format
65
- # format.set_bold()
66
- # format.set_color('red')
67
- # format.set_align('center')
68
- #
69
- # # Write a formatted and unformatted string, row and column notation.
70
- # col = row = 0
71
- # worksheet.write(row, col, 'Hi Excel!', format)
72
- # worksheet.write(1, col, 'Hi Excel!')
73
- #
74
- # # Write a number and a formula using A1 notation
75
- # worksheet.write('A3', 1.2345)
76
- # worksheet.write('A4', '=SIN(PI()/4)')
77
- #
78
- # # Save to ruby.xls
79
- # workbook.close
80
- #
81
- # == Description
82
- #
83
- # WriteExcel can be used to create a cross-platform Excel binary file.
84
- # Multiple worksheets can be added to a workbook and formatting can be applied
85
- # to cells. Text, numbers, formulas, hyperlinks and images can be written to
86
- # the cells.
87
- #
88
- # The Excel file produced by this gem is compatible with 97, 2000, 2002, 2003
89
- # and 2007.
90
- #
91
- # WriteExcel will work on the majority of Windows, UNIX and Mac platforms.
92
- # Generated files are also compatible with the Linux/UNIX spreadsheet
93
- # applications Gnumeric and OpenOffice.org.
94
- #
95
- # This module cannot be used to write to an existing Excel file
96
- #
97
- # This library is converted from Spreadsheet::WriteExcel module of Perl.
98
- # http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel-2.37/
99
- #
100
- # == Quick Start
101
- #
102
- # WriteExcel tries to provide an interface to as many of Excel's features as
103
- # possible. As a result there is a lot of documentation to accompany the
104
- # interface and it can be difficult at first glance to see what it important
105
- # and what is not. So for those of you who prefer to assemble Ikea furniture
106
- # first and then read the instructions, here are four easy steps:
107
- #
108
- # 1. Create a new Excel workbook (i.e. file) using new().
109
- #
110
- # 2. Add a worksheet to the new workbook using add_worksheet().
111
- #
112
- # 3. Write to the worksheet using write().
113
- #
114
- # 4. Save to file.
115
- #
116
- # Like this:
117
- #
118
- # require 'WriteExcel' # Step 0
119
- #
120
- # workbook = WriteExcel.new('ruby.xls') # Step 1
121
- # worksheet = workbook.add_worksheet # Step 2
122
- # worksheet.write('A1', 'Hi Excel!') # Step 3
123
- # workbook.close # Step 4
124
- #
125
- # This will create an Excel file called ruby.xls with a single worksheet and the
126
- # text 'Hi Excel!' in the relevant cell. And that's it. Okay, so there is
127
- # actually a zeroth step as well, but use WriteExcel goes without saying. There
128
- # are also many examples that come with the distribution and which you can
129
- # use to get you started. See EXAMPLES.
130
- #
131
- # = Workbook methods
132
- #
133
- # The WriteExcel module provides an object oriented interface
134
- # to a new Excel workbook. The following methods are available through
135
- # a new workbook.
136
- #
137
- # new()
138
- # add_worksheet()
139
- # add_format()
140
- # add_chart()
141
- # add_chart_ext()
142
- # close()
143
- # compatibility_mode()
144
- # set_properties()
145
- # define_name()
146
- # set_tempdir()
147
- # set_custom_color()
148
- # sheets()
149
- # set_1904()
150
- # set_codepage()
151
- #
152
- # = Worksheet methods
153
- #
154
- # A new worksheet is created by calling the add_worksheet() method from
155
- # a workbook object:
156
- #
157
- # worksheet1 = workbook.add_worksheet
158
- # worksheet2 = workbook.add_worksheet
159
- #
160
- # The following methods are available through a new worksheet:
161
- #
162
- # write()
163
- # write_number()
164
- # write_string()
165
- # write_utf16be_string()
166
- # write_utf16le_string()
167
- # keep_leading_zeros()
168
- # write_blank()
169
- # write_row()
170
- # write_col()
171
- # write_date_time()
172
- # write_url()
173
- # write_url_range()
174
- # write_formula()
175
- # store_formula()
176
- # repeat_formula()
177
- # write_comment()
178
- # show_comments()
179
- # add_write_handler() (* not implemented yet)
180
- # insert_image()
181
- # insert_chart()
182
- # data_validation()
183
- # get_name()
184
- # activate()
185
- # select()
186
- # hide()
187
- # set_first_sheet()
188
- # protect()
189
- # set_selection()
190
- # set_row()
191
- # set_column()
192
- # outline_settings()
193
- # freeze_panes()
194
- # split_panes()
195
- # merge_range()
196
- # set_zoom()
197
- # right_to_left()
198
- # hide_zero()
199
- # set_tab_color()
200
- # autofilter()
201
- #
202
- # == Cell notation
203
- # WriteExcel supports two forms of notation to designate the position of cells:
204
- # Row-column notation and A1 notation.
205
- #
206
- # Row-column notation uses a zero based index for both row and column while A1
207
- # notation uses the standard Excel alphanumeric sequence of column letter and
208
- # 1-based row. For example:
209
- #
210
- # (0, 0) # The top left cell in row-column notation.
211
- # ('A1') # The top left cell in A1 notation.
212
- #
213
- # (1999, 29) # Row-column notation.
214
- # ('AD2000') # The same cell in A1 notation.
215
- #
216
- # Row-column notation is useful if you are referring to cells
217
- # programmatically:
218
- #
219
- # (0 .. 10).each do |i|
220
- # worksheet.write(i, 0, 'Hello') # Cells A1 to A10
221
- # end
222
- #
223
- # A1 notation is useful for setting up a worksheet manually and for working
224
- # with formulas:
225
- #
226
- # worksheet.write('H1', 200)
227
- # worksheet.write('H2', '=H1+1')
228
- #
229
- # In formulas and applicable methods you can also use the A:A column notation:
230
- #
231
- # worksheet.write('A1', '=SUM(B:B)')
232
- #
233
- # For simplicity, the parameter lists for the worksheet method calls in the
234
- # following sections are given in terms of row-column notation. In all cases
235
- # it is also possible to use A1 notation.
236
- #
237
- # Note: in Excel it is also possible to use a R1C1 notation. This is not
238
- # supported by WriteExcel.
239
- #
240
- # ==PAGE SET-UP METHODS
241
- #
242
- # Page set-up methods affect the way that a worksheet looks when it is printed.
243
- # They control features such as page headers and footers and margins. These
244
- # methods are really just standard worksheet methods. They are documented
245
- # here in a separate section for the sake of clarity.
246
- #
247
- # The following methods are available for page set-up:
248
- #
249
- # set_landscape()
250
- # set_portrait()
251
- # set_page_view()
252
- # set_paper()
253
- # center_horizontally()
254
- # center_vertically()
255
- # set_margins()
256
- # set_header()
257
- # set_footer()
258
- # repeat_rows()
259
- # repeat_columns()
260
- # hide_gridlines()
261
- # print_row_col_headers()
262
- # print_area()
263
- # print_across()
264
- # fit_to_pages()
265
- # set_start_page()
266
- # set_print_scale()
267
- # set_h_pagebreaks()
268
- # set_v_pagebreaks()
269
- #
270
- # A common requirement when working with WriteExcel is to apply the same page
271
- # set-up features to all of the worksheets in a workbook. To do this you can use
272
- # the sheets() method of the workbook class to access the array of worksheets
273
- # in a workbook:
274
- #
275
- # workbook.sheets.each do |worksheet|
276
- # worksheet.set_landscape
277
- # end
278
- #
279
- # ==CELL FORMATTING
280
- #
281
- # This section describes the methods and properties that are available for
282
- # formatting cells in Excel. The properties of a cell that can be formatted
283
- # include: fonts, colours, patterns, borders, alignment and number formatting.
284
- #
285
- # ===Creating and using a Format object
286
- #
287
- # Cell formatting is defined through a Format object. Format objects are
288
- # created by calling the workbook add_format() method as follows:
289
- #
290
- # format1 = workbook.add_format # Set properties later
291
- # format2 = workbook.add_format(property hash..) # Set at creation
292
- #
293
- # The format object holds all the formatting properties that can be applied
294
- # to a cell, a row or a column. The process of setting these properties is
295
- # discussed in the next section.
296
- #
297
- # Once a Format object has been constructed and it properties have been set
298
- # it can be passed as an argument to the worksheet write methods as follows:
299
- #
300
- # worksheet.write(0, 0, 'One', format)
301
- # worksheet.write_string(1, 0, 'Two', format)
302
- # worksheet.write_number(2, 0, 3, format)
303
- # worksheet.write_blank(3, 0, format)
304
- #
305
- # Formats can also be passed to the worksheet set_row() and set_column()
306
- # methods to define the default property for a row or column.
307
- #
308
- # worksheet.set_row(0, 15, format)
309
- # worksheet.set_column(0, 0, 15, format)
310
- #
311
- # ===Format methods and Format properties
312
- #
313
- # The following table shows the Excel format categories, the formatting
314
- # properties that can be applied and the equivalent object method:
315
- #
316
- # Category Description Property Method Name
317
- # -------- ----------- -------- -----------
318
- # Font Font type font set_font()
319
- # Font size size set_size()
320
- # Font color color set_color()
321
- # Bold bold set_bold()
322
- # Italic italic set_italic()
323
- # Underline underline set_underline()
324
- # Strikeout font_strikeout set_font_strikeout()
325
- # Super/Subscript font_script set_font_script()
326
- # Outline font_outline set_font_outline()
327
- # Shadow font_shadow set_font_shadow()
328
- #
329
- # Number Numeric format num_format set_num_format()
330
- #
331
- # Protection Lock cells locked set_locked()
332
- # Hide formulas hidden set_hidden()
333
- #
334
- # Alignment Horizontal align align set_align()
335
- # Vertical align valign set_align()
336
- # Rotation rotation set_rotation()
337
- # Text wrap text_wrap set_text_wrap()
338
- # Justify last text_justlast set_text_justlast()
339
- # Center across center_across set_center_across()
340
- # Indentation indent set_indent()
341
- # Shrink to fit shrink set_shrink()
342
- #
343
- # Pattern Cell pattern pattern set_pattern()
344
- # Background color bg_color set_bg_color()
345
- # Foreground color fg_color set_fg_color()
346
- #
347
- # Border Cell border border set_border()
348
- # Bottom border bottom set_bottom()
349
- # Top border top set_top()
350
- # Left border left set_left()
351
- # Right border right set_right()
352
- # Border color border_color set_border_color()
353
- # Bottom color bottom_color set_bottom_color()
354
- # Top color top_color set_top_color()
355
- # Left color left_color set_left_color()
356
- # Right color right_color set_right_color()
357
- #
358
- # There are two ways of setting Format properties: by using the object method
359
- # interface or by setting the property directly. For example, a typical use of
360
- # the method interface would be as follows:
361
- #
362
- # format = workbook.add_format
363
- # format.set_bold
364
- # format.set_color('red')
365
- #
366
- # By comparison the properties can be set directly by passing a hash of
367
- # properties to the Format constructor:
368
- #
369
- # format = workbook.add_format(:bold => 1, :color => 'red')
370
- #
371
- # or after the Format has been constructed by means of the
372
- # set_format_properties() method as follows:
373
- #
374
- # format = workbook.add_format
375
- # format.set_format_properties(:bold => 1, :color => 'red')
376
- #
377
- # You can also store the properties in one or more named hashes and pass them
378
- # to the required method:
379
- #
380
- # font = {
381
- # :font => 'Arial',
382
- # :size => 12,
383
- # :color => 'blue',
384
- # :bold => 1
385
- # }
386
- #
387
- # shading = {
388
- # :bg_color => 'green',
389
- # :pattern => 1
390
- # }
391
- #
392
- # format1 = workbook.add_format(font) # Font only
393
- # format2 = workbook.add_format(font, shading) # Font and shading
394
- #
395
- # The provision of two ways of setting properties might lead you to wonder
396
- # which is the best way. The method mechanism may be better is you prefer
397
- # setting properties via method calls (which the author did when they were
398
- # code was first written) otherwise passing properties to the constructor has
399
- # proved to be a little more flexible and self documenting in practice. An
400
- # additional advantage of working with property hashes is that it allows you to
401
- # share formatting between workbook objects as shown in the example above.
402
- #
403
- #--
404
- #
405
- # did not converted ???
406
- #
407
- # The Perl/Tk style of adding properties is also supported:
408
- #
409
- # %font = (
410
- # -font => 'Arial',
411
- # -size => 12,
412
- # -color => 'blue',
413
- # -bold => 1,
414
- # )
415
- #++
416
- #
417
- # ===Working with formats
418
- #
419
- # The default format is Arial 10 with all other properties off.
420
- #
421
- # Each unique format in WriteExcel must have a corresponding
422
- # Format object. It isn't possible to use a Format with a write() method and
423
- # then redefine the Format for use at a later stage. This is because a Format
424
- # is applied to a cell not in its current state but in its final state.
425
- # Consider the following example:
426
- #
427
- # format = workbook.add_format
428
- # format.set_bold
429
- # format.set_color('red')
430
- # worksheet.write('A1', 'Cell A1', format)
431
- # format.set_color('green')
432
- # worksheet.write('B1', 'Cell B1', format)
433
- #
434
- # Cell A1 is assigned the Format _format_ which is initially set to the colour
435
- # red. However, the colour is subsequently set to green. When Excel displays
436
- # Cell A1 it will display the final state of the Format which in this case
437
- # will be the colour green.
438
- #
439
- # In general a method call without an argument will turn a property on,
440
- # for example:
441
- #
442
- # format1 = workbook.add_format
443
- # format1.set_bold # Turns bold on
444
- # format1.set_bold(1) # Also turns bold on
445
- # format1.set_bold(0) # Turns bold off
446
- #
447
- # ==FORMAT METHODS
448
- #
449
- # The Format object methods are described in more detail in the following
450
- # sections. In addition, there is a Ruby program called formats.rb in the
451
- # examples directory of the WriteExcel distribution. This program creates an
452
- # Excel workbook called formats.xls which contains examples of almost all
453
- # the format types.
454
- #
455
- # The following Format methods are available:
456
- #
457
- # set_font()
458
- # set_size()
459
- # set_color()
460
- # set_bold()
461
- # set_italic()
462
- # set_underline()
463
- # set_font_strikeout()
464
- # set_font_script()
465
- # set_font_outline()
466
- # set_font_shadow()
467
- # set_num_format()
468
- # set_locked()
469
- # set_hidden()
470
- # set_align()
471
- # set_rotation()
472
- # set_text_wrap()
473
- # set_text_justlast()
474
- # set_center_across()
475
- # set_indent()
476
- # set_shrink()
477
- # set_pattern()
478
- # set_bg_color()
479
- # set_fg_color()
480
- # set_border()
481
- # set_bottom()
482
- # set_top()
483
- # set_left()
484
- # set_right()
485
- # set_border_color()
486
- # set_bottom_color()
487
- # set_top_color()
488
- # set_left_color()
489
- # set_right_color()
490
- #
491
- # The above methods can also be applied directly as properties. For example
492
- # format.set_bold is equivalent to workbook.add_format(:bold => 1).
493
- #
494
- # ==COLOURS IN EXCEL
495
- #
496
- # Excel provides a colour palette of 56 colours. In WriteExcel these colours
497
- # are accessed via their palette index in the range 8..63. This index is used
498
- # to set the colour of fonts, cell patterns and cell borders. For example:
499
- #
500
- # format = workbook.add_format(
501
- # :color => 12, # index for blue
502
- # :font => 'Arial',
503
- # :size => 12,
504
- # :bold => 1
505
- # )
506
- #
507
- # The most commonly used colours can also be accessed by name. The name acts
508
- # as a simple alias for the colour index:
509
- #
510
- # black => 8
511
- # blue => 12
512
- # brown => 16
513
- # cyan => 15
514
- # gray => 23
515
- # green => 17
516
- # lime => 11
517
- # magenta => 14
518
- # navy => 18
519
- # orange => 53
520
- # pink => 33
521
- # purple => 20
522
- # red => 10
523
- # silver => 22
524
- # white => 9
525
- # yellow => 13
526
- #
527
- # For example:
528
- #
529
- # font = workbook.add_format(:color => 'red')
530
- #
531
- # Users of VBA in Excel should note that the equivalent colour indices are in
532
- # the range 1..56 instead of 8..63.
533
- #
534
- # If the default palette does not provide a required colour you can override
535
- # one of the built-in values. This is achieved by using the set_custom_color()
536
- # workbook method to adjust the RGB (red green blue) components of the colour:
537
- #
538
- # ferrari = workbook.set_custom_color(40, 216, 12, 12)
539
- #
540
- # format = workbook.add_format(
541
- # :bg_color => ferrari,
542
- # :pattern => 1,
543
- # :border => 1
544
- # )
545
- #
546
- # worksheet.write_blank('A1', format)
547
- #
548
- # You may also find the following links helpful:
549
- #
550
- # A detailed look at Excel's colour palette:
551
- # http://www.mvps.org/dmcritchie/excel/colors.htm
552
- #
553
- # A decimal RGB chart: http://www.hypersolutions.org/pages/rgbdec.html
554
- #
555
- # A hex RGB chart: : http://www.hypersolutions.org/pages/rgbhex.html
556
- #
557
- # ==DATES AND TIME IN EXCEL
558
- #
559
- # There are two important things to understand about dates and times in Excel:
560
- #
561
- # 1. A date/time in Excel is a real number plus an Excel number format.
562
- #
563
- # 2. WriteExcel doesn't automatically convert date/time strings in write() to
564
- # an Excel date/time.
565
- #
566
- # These two points are explained in more detail below along with some
567
- # suggestions on how to convert times and dates to the required format.
568
- #
569
- # ===An Excel date/time is a number plus a format
570
- #
571
- # If you write a date string with write() then all you will get is a string:
572
- #
573
- # worksheet.write('A1', '02/03/04') # !! Writes a string not a date. !!
574
- #
575
- # Dates and times in Excel are represented by real numbers, for example
576
- # "Jan 1 2001 12:30 AM" is represented by the number 36892.521.
577
- #
578
- # The integer part of the number stores the number of days since the epoch
579
- # and the fractional part stores the percentage of the day.
580
- #
581
- # A date or time in Excel is just like any other number. To have the number
582
- # display as a date you must apply an Excel number format to it. Here are
583
- # some examples.
584
- #
585
- # #!/usr/bin/ruby -w
586
- #
587
- # require 'writeexcel'
588
- #
589
- # workbook = WriteExcel.new('date_examples.xls')
590
- # worksheet = workbook.add_worksheet
591
- #
592
- # worksheet.set_column('A:A', 30) # For extra visibility.
593
- #
594
- # number = 39506.5
595
- #
596
- # worksheet.write('A1', number) # 39506.5
597
- #
598
- # format2 = workbook.add_format(:num_format => 'dd/mm/yy')
599
- # worksheet.write('A2', number , format2); # 28/02/08
600
- #
601
- # format3 = workbook.add_format(:num_format => 'mm/dd/yy')
602
- # worksheet.write('A3', number , format3); # 02/28/08
603
- #
604
- # format4 = workbook.add_format(:num_format => 'd-m-yyyy')
605
- # worksheet.write('A4', .number , format4) # 28-2-2008
606
- #
607
- # format5 = workbook.add_format(:num_format => 'dd/mm/yy hh:mm')
608
- # worksheet.write('A5', number , format5) # 28/02/08 12:00
609
- #
610
- # format6 = workbook.add_format(:num_format => 'd mmm yyyy')
611
- # worksheet.write('A6', number , format6) # 28 Feb 2008
612
- #
613
- # format7 = workbook.add_format(:num_format => 'mmm d yyyy hh:mm AM/PM')
614
- # worksheet.write('A7', number , format7) # Feb 28 2008 12:00 PM
615
- #
616
- # ===WriteExcel doesn't automatically convert date/time strings
617
- #
618
- # WriteExcel doesn't automatically convert input date strings into Excel's
619
- # formatted date numbers due to the large number of possible date formats
620
- # and also due to the possibility of misinterpretation.
621
- #
622
- # For example, does 02/03/04 mean March 2 2004, February 3 2004 or even March
623
- # 4 2002.
624
- #
625
- # Therefore, in order to handle dates you will have to convert them to numbers
626
- # and apply an Excel format. Some methods for converting dates are listed in
627
- # the next section.
628
- #
629
- # The most direct way is to convert your dates to the ISO8601
630
- # yyyy-mm-ddThh:mm:ss.sss date format and use the write_date_time() worksheet
631
- # method:
632
- #
633
- # worksheet.write_date_time('A2', '2001-01-01T12:20', format)
634
- #
635
- # See the write_date_time() section of the documentation for more details.
636
- #
637
- # A general methodology for handling date strings with write_date_time() is:
638
- #
639
- # 1. Identify incoming date/time strings with a regex.
640
- # 2. Extract the component parts of the date/time using the same regex.
641
- # 3. Convert the date/time to the ISO8601 format.
642
- # 4. Write the date/time using write_date_time() and a number format.
643
- #
644
- # Here is an example:
645
- #
646
- # #!/usr/bin/ruby -w
647
- #
648
- # require 'writeexcel'
649
- #
650
- # workbook = WriteExcel.new('example.xls')
651
- # worksheet = workbook.add_worksheet
652
- #
653
- # # Set the default format for dates.
654
- # date_format = workbook.add_format(:num_format => 'mmm d yyyy')
655
- #
656
- # # Increase column width to improve visibility of data.
657
- # worksheet.set_column('A:C', 20)
658
- #
659
- # data = [
660
- # %w(Item Cost Date),
661
- # %w(Book 10 1/9/2007),
662
- # %w(Beer 4 12/9/2007),
663
- # %w(Bed 500 5/10/2007)
664
- # ]
665
- #
666
- # # Simulate reading from a data source.
667
- # row = 0
668
- #
669
- # data.each do |row_data|
670
- # col = 0
671
- # row_data.each do |item|
672
- #
673
- # # Match dates in the following formats: d/m/yy, d/m/yyyy
674
- # if item =~ %r[^(\d{1,2})/(\d{1,2})/(\d{4})$]
675
- # # Change to the date format required by write_date_time().
676
- # date = sprintf "%4d-%02d-%02dT", $3, $2, $1
677
- # worksheet.write_date_time(row, col, date, date_format)
678
- # else
679
- # # Just plain data
680
- # worksheet.write(row, col, item)
681
- # end
682
- # col += 1
683
- # end
684
- # row += 1
685
- # end
686
- #
687
- #--
688
- # For a slightly more advanced solution you can modify the write() method to
689
- # handle date formats of your choice via the add_write_handler() method. See
690
- # the add_write_handler() section of the docs and the write_handler3.rb and
691
- # write_handler4.rb programs in the examples directory of the distro.
692
- #++
693
- #
694
- # ==OUTLINES AND GROUPING IN EXCEL
695
- #
696
- # Excel allows you to group rows or columns so that they can be hidden or
697
- # displayed with a single mouse click. This feature is referred to as outlines.
698
- #
699
- # Outlines can reduce complex data down to a few salient sub-totals or
700
- # summaries.
701
- #
702
- # This feature is best viewed in Excel but the following is an ASCII
703
- # representation of what a worksheet with three outlines might look like. Rows
704
- # 3-4 and rows 7-8 are grouped at level 2. Rows 2-9 are grouped at level 1.
705
- # The lines at the left hand side are called outline level bars.
706
- #
707
- # ------------------------------------------
708
- # 1 2 3 | | A | B | C | D | ...
709
- # ------------------------------------------
710
- # _ | 1 | A | | | | ...
711
- # | _ | 2 | B | | | | ...
712
- # | | | 3 | (C) | | | | ...
713
- # | | | 4 | (D) | | | | ...
714
- # | - | 5 | E | | | | ...
715
- # | _ | 6 | F | | | | ...
716
- # | | | 7 | (G) | | | | ...
717
- # | | | 8 | (H) | | | | ...
718
- # | - | 9 | I | | | | ...
719
- # - | . | ... | ... | ... | ... | ...
720
- #
721
- # Clicking the minus sign on each of the level 2 outlines will collapse and
722
- # hide the data as shown in the next figure. The minus sign changes to a plus
723
- # sign to indicate that the data in the outline is hidden.
724
- #
725
- # ------------------------------------------
726
- # 1 2 3 | | A | B | C | D | ...
727
- # ------------------------------------------
728
- # _ | 1 | A | | | | ...
729
- # | | 2 | B | | | | ...
730
- # | + | 5 | E | | | | ...
731
- # | | 6 | F | | | | ...
732
- # | + | 9 | I | | | | ...
733
- # - | . | ... | ... | ... | ... | ...
734
- #
735
- # Clicking on the minus sign on the level 1 outline will collapse the
736
- # remaining rows as follows:
737
- #
738
- # ------------------------------------------
739
- # 1 2 3 | | A | B | C | D | ...
740
- # ------------------------------------------
741
- # | 1 | A | | | | ...
742
- # + | . | ... | ... | ... | ... | ...
743
- #
744
- # Grouping in WriteExcel is achieved by setting the outline level via the
745
- # set_row() and set_column() worksheet methods:
746
- #
747
- # set_row(row, height, format, hidden, level, collapsed)
748
- # set_column(first_col, last_col, width, format, hidden, level, collapsed)
749
- #
750
- # The following example sets an outline level of 1 for rows 1 and 2
751
- # (zero-indexed) and columns B to G. The parameters _height_ and _format_ are
752
- # assigned default values since they are undefined:
753
- #
754
- # worksheet.set_row(1, nil, nil, 0, 1)
755
- # worksheet.set_row(2, nil, nil, 0, 1)
756
- # worksheet.set_column('B:G', nil, nil, 0, 1)
757
- #
758
- # Excel allows up to 7 outline levels. Therefore the _level_ parameter should
759
- # be in the range 0 <= _level_ <= 7.
760
- #
761
- # Rows and columns can be collapsed by setting the _hidden_ flag for the hidden
762
- # rows/columns and setting the _collapsed_ flag for the row/column that has
763
- # the collapsed + symbol:
764
- #
765
- # worksheet.set_row(1, nil, nil, 1, 1)
766
- # worksheet.set_row(2, nil, nil, 1, 1)
767
- # worksheet.set_row(3, nil, nil, 0, 0, 1) # Collapsed flag.
768
- #
769
- # worksheet.set_column('B:G', nil, nil, 1, 1)
770
- # worksheet.set_column('H:H', nil, nil, 0, 0, 1) # Collapsed flag.
771
- #
772
- # Note: Setting the _collapsed_ flag is particularly important for
773
- # compatibility with OpenOffice.org and Gnumeric.
774
- #
775
- # For a more complete example see the outline.rb
776
- # and outline_collapsed.rb
777
- # programs in the examples directory of the distro.
778
- #
779
- # Some additional outline properties can be set via the outline_settings()
780
- # worksheet method, see above.
781
- #
782
- # ==DATA VALIDATION IN EXCEL
783
- #
784
- # Data validation is a feature of Excel which allows you to restrict the data
785
- # that a users enters in a cell and to display help and warning messages. It
786
- # also allows you to restrict input to values in a drop down list.
787
- #
788
- # A typical use case might be to restrict data in a cell to integer values in
789
- # a certain range, to provide a help message to indicate the required value and
790
- # to issue a warning if the input data doesn't meet the stated criteria.
791
- # In WriteExcel we could do that as follows:
792
- #
793
- # worksheet.data_validation('B3',
794
- # {
795
- # :validate => 'integer',
796
- # :criteria => 'between',
797
- # :minimum => 1,
798
- # :maximum => 100,
799
- # :input_title => 'Input an integer:',
800
- # :input_message => 'Between 1 and 100',
801
- # :error_message => 'Sorry, try again.'
802
- # })
803
- #
804
- # The above example would look like this in Excel:
805
- # http://homepage.eircom.net/~jmcnamara/perl/data_validation.jpg.
806
- #
807
- # For more information on data validation see the following Microsoft
808
- # support article "Description and examples of data validation in Excel":
809
- # http://support.microsoft.com/kb/211485.
810
- #
811
- # ==FORMULAS AND FUNCTIONS IN EXCEL
812
- #
813
- # ===Caveats
814
- #
815
- # The first thing to note is that there are still some outstanding issues
816
- # with the implementation of formulas and functions:
817
- #
818
- # 1. Writing a formula is much slower than writing the equivalent string.
819
- # 2. You cannot use array constants, i.e. {1;2;3}, in functions.
820
- # 3. Unary minus isn't supported.
821
- # 4. Whitespace is not preserved around operators.
822
- # 5. Named ranges are not supported.
823
- # 6. Array formulas are not supported.
824
- #
825
- # However, these constraints will be removed in future versions. They are
826
- # here because of a trade-off between features and time. Also, it is possible
827
- # to work around issue 1 using the store_formula() and repeat_formula()
828
- # methods as described later in this section.
829
- #
830
- # ===Introduction
831
- #
832
- # The following is a brief introduction to formulas and functions in Excel
833
- # and WriteExcel.
834
- #
835
- # A formula is a string that begins with an equals sign:
836
- #
837
- # '=A1+B1'
838
- # '=AVERAGE(1, 2, 3)'
839
- #
840
- # The formula can contain numbers, strings, boolean values, cell references,
841
- # cell ranges and functions. Named ranges are not supported. Formulas should
842
- # be written as they appear in Excel, that is cells and functions must be
843
- # in uppercase.
844
- #
845
- # Cells in Excel are referenced using the A1 notation system where the
846
- # column is designated by a letter and the row by a number. Columns
847
- # range from A to IV i.e. 0 to 255, rows range from 1 to 65536.
848
- #--
849
- # The Spreadsheet::WriteExcel::Utility module that is included in the distro
850
- # contains helper functions for dealing with A1 notation, for example:
851
- #
852
- # use Spreadsheet::WriteExcel::Utility;
853
- #
854
- # ($row, $col) = xl_cell_to_rowcol('C2'); # (1, 2)
855
- # $str = xl_rowcol_to_cell(1, 2); # C2
856
- #++
857
- #
858
- # The Excel $ notation in cell references is also supported. This allows you
859
- # to specify whether a row or column is relative or absolute. This only has
860
- # an effect if the cell is copied. The following examples show relative and
861
- # absolute values.
862
- #
863
- # '=A1' # Column and row are relative
864
- # '=$A1' # Column is absolute and row is relative
865
- # '=A$1' # Column is relative and row is absolute
866
- # '=$A$1' # Column and row are absolute
867
- #
868
- # Formulas can also refer to cells in other worksheets of the current
869
- # workbook. For example:
870
- #
871
- # '=Sheet2!A1'
872
- # '=Sheet2!A1:A5'
873
- # '=Sheet2:Sheet3!A1'
874
- # '=Sheet2:Sheet3!A1:A5'
875
- # q{='Test Data'!A1}
876
- # q{='Test Data1:Test Data2'!A1}
877
- #
878
- # The sheet reference and the cell reference are separated by ! the exclamation
879
- # mark symbol. If worksheet names contain spaces, commas o parentheses then Excel
880
- # requires that the name is enclosed in single quotes as shown in the last two
881
- # examples above. In order to avoid using a lot of escape characters you can
882
- # use the quote operator %q{} to protect the quotes. Only valid sheet names that
883
- # have been added using the add_worksheet() method can be used in formulas.
884
- # You cannot reference external workbooks.
885
- #
886
- # The following table lists the operators that are available in Excel's formulas.
887
- # The majority of the operators are the same as Perl's, differences are indicated:
888
- #
889
- # Arithmetic operators:
890
- # =====================
891
- # Operator Meaning Example
892
- # + Addition 1+2
893
- # - Subtraction 2-1
894
- # * Multiplication 2*3
895
- # / Division 1/4
896
- # ^ Exponentiation 2^3 # Equivalent to **
897
- # - Unary minus -(1+2) # Not yet supported
898
- # % Percent (Not modulus) 13% # Not supported, [1]
899
- #
900
- # Comparison operators:
901
- # =====================
902
- # Operator Meaning Example
903
- # = Equal to A1 = B1 # Equivalent to ==
904
- # <> Not equal to A1 <> B1 # Equivalent to !=
905
- # > Greater than A1 > B1
906
- # < Less than A1 < B1
907
- # >= Greater than or equal to A1 >= B1
908
- # <= Less than or equal to A1 <= B1
909
- #
910
- # String operator:
911
- # ================
912
- # Operator Meaning Example
913
- # & Concatenation "Hello " & "World!" # [2]
914
- #
915
- # Reference operators:
916
- # ====================
917
- # Operator Meaning Example
918
- # : Range operator A1:A4 # [3]
919
- # , Union operator SUM(1, 2+2, B3) # [4]
920
- #
921
- # Notes:
922
- # [1]: You can get a percentage with formatting and modulus with MOD().
923
- # [2]: Equivalent to ("Hello " . "World!") in Perl.
924
- # [3]: This range is equivalent to cells A1, A2, A3 and A4.
925
- # [4]: The comma behaves like the list separator in Perl.
926
- #
927
- # The range and comma operators can have different symbols in non-English
928
- # versions of Excel. These will be supported in a later version of WriteExcel.
929
- # European users of Excel take note:
930
- #
931
- # worksheet.write('A1', '=SUM(1; 2; 3)') # Wrong!!
932
- # worksheet.write('A1', '=SUM(1, 2, 3)') # Okay
933
- #
934
- # The following table lists all of the core functions supported by
935
- # Excel 5 and WriteExcel. Any additional functions that are available through
936
- # the "Analysis ToolPak" or other add-ins are not supported. These functions
937
- # have all been tested to verify that they work.
938
- #
939
- # ABS DB INDIRECT NORMINV SLN
940
- # ACOS DCOUNT INFO NORMSDIST SLOPE
941
- # ACOSH DCOUNTA INT NORMSINV SMALL
942
- # ADDRESS DDB INTERCEPT NOT SQRT
943
- # AND DEGREES IPMT NOW STANDARDIZE
944
- # AREAS DEVSQ IRR NPER STDEV
945
- # ASIN DGET ISBLANK NPV STDEVP
946
- # ASINH DMAX ISERR ODD STEYX
947
- # ATAN DMIN ISERROR OFFSET SUBSTITUTE
948
- # ATAN2 DOLLAR ISLOGICAL OR SUBTOTAL
949
- # ATANH DPRODUCT ISNA PEARSON SUM
950
- # AVEDEV DSTDEV ISNONTEXT PERCENTILE SUMIF
951
- # AVERAGE DSTDEVP ISNUMBER PERCENTRANK SUMPRODUCT
952
- # BETADIST DSUM ISREF PERMUT SUMSQ
953
- # BETAINV DVAR ISTEXT PI SUMX2MY2
954
- # BINOMDIST DVARP KURT PMT SUMX2PY2
955
- # CALL ERROR.TYPE LARGE POISSON SUMXMY2
956
- # CEILING EVEN LEFT POWER SYD
957
- # CELL EXACT LEN PPMT T
958
- # CHAR EXP LINEST PROB TAN
959
- # CHIDIST EXPONDIST LN PRODUCT TANH
960
- # CHIINV FACT LOG PROPER TDIST
961
- # CHITEST FALSE LOG10 PV TEXT
962
- # CHOOSE FDIST LOGEST QUARTILE TIME
963
- # CLEAN FIND LOGINV RADIANS TIMEVALUE
964
- # CODE FINV LOGNORMDIST RAND TINV
965
- # COLUMN FISHER LOOKUP RANK TODAY
966
- # COLUMNS FISHERINV LOWER RATE TRANSPOSE
967
- # COMBIN FIXED MATCH REGISTER.ID TREND
968
- # CONCATENATE FLOOR MAX REPLACE TRIM
969
- # CONFIDENCE FORECAST MDETERM REPT TRIMMEAN
970
- # CORREL FREQUENCY MEDIAN RIGHT TRUE
971
- # COS FTEST MID ROMAN TRUNC
972
- # COSH FV MIN ROUND TTEST
973
- # COUNT GAMMADIST MINUTE ROUNDDOWN TYPE
974
- # COUNTA GAMMAINV MINVERSE ROUNDUP UPPER
975
- # COUNTBLANK GAMMALN MIRR ROW VALUE
976
- # COUNTIF GEOMEAN MMULT ROWS VAR
977
- # COVAR GROWTH MOD RSQ VARP
978
- # CRITBINOM HARMEAN MODE SEARCH VDB
979
- # DATE HLOOKUP MONTH SECOND VLOOKUP
980
- # DATEVALUE HOUR N SIGN WEEKDAY
981
- # DAVERAGE HYPGEOMDIST NA SIN WEIBULL
982
- # DAY IF NEGBINOMDIST SINH YEAR
983
- # DAYS360 INDEX NORMDIST SKEW ZTEST
984
- #
985
- #--
986
- # You can also modify the module to support function names in the following
987
- # languages: German, French, Spanish, Portuguese, Dutch, Finnish, Italian and
988
- # Swedish. See the function_locale.pl program in the examples directory of the distro.
989
- #++
990
- #
991
- # For a general introduction to Excel's formulas and an explanation of the
992
- # syntax of the function refer to the Excel help files or the following:
993
- # http://office.microsoft.com/en-us/assistance/CH062528031033.aspx.
994
- #
995
- # If your formula doesn't work in Spreadsheet::WriteExcel try the following:
996
- #
997
- # 1. Verify that the formula works in Excel (or Gnumeric or OpenOffice.org).
998
- # 2. Ensure that it isn't on the Caveats list shown above.
999
- # 3. Ensure that cell references and formula names are in uppercase.
1000
- # 4. Ensure that you are using ':' as the range operator, A1:A4.
1001
- # 5. Ensure that you are using ',' as the union operator, SUM(1,2,3).
1002
- # 6. Ensure that the function is in the above table.
1003
- #
1004
- # If you go through steps 1-6 and you still have a problem, mail me.
1005
- #
1006
- # ===Improving performance when working with formulas
1007
- #
1008
- # Writing a large number of formulas with Spreadsheet::WriteExcel can be slow.
1009
- # This is due to the fact that each formula has to be parsed and with the
1010
- # current implementation this is computationally expensive.
1011
- #
1012
- # However, in a lot of cases the formulas that you write will be quite
1013
- # similar, for example:
1014
- #
1015
- # worksheet.write_formula('B1', '=A1 * 3 + 50', format)
1016
- # worksheet.write_formula('B2', '=A2 * 3 + 50', format)
1017
- # ...
1018
- # ...
1019
- # worksheet.write_formula('B99', '=A999 * 3 + 50', format)
1020
- # worksheet.write_formula('B1000', '=A1000 * 3 + 50', format)
1021
- #
1022
- # In this example the cell reference changes in iterations from A1 to A1000.
1023
- # The parser treats this variable as a token and arranges it according to
1024
- # predefined rules. However, since the parser is oblivious to the value of
1025
- # the token, it is essentially performing the same calculation 1000 times.
1026
- # This is inefficient.
1027
- #
1028
- # The way to avoid this inefficiency and thereby speed up the writing of
1029
- # formulas is to parse the formula once and then repeatedly substitute
1030
- # similar tokens.
1031
- #
1032
- # A formula can be parsed and stored via the store_formula() worksheet method.
1033
- # You can then use the repeat_formula() method to substitute _pattern_,
1034
- # _replace_ pairs in the stored formula:
1035
- #
1036
- # formula = worksheet.store_formula('=A1 * 3 + 50')
1037
- #
1038
- # (0...1000).each do |row|
1039
- # worksheet.repeat_formula(row, 1, formula, format, 'A1', 'A' + (row +1).to_s)
1040
- # end
1041
- #
1042
- # On an arbitrary test machine this method was 10 times faster than the
1043
- # brute force method shown above.
1044
- #
1045
- # It should be noted however that the overall speed of direct formula parsing
1046
- # will be improved in a future version.
1047
- #
1048
- # ==Chart
1049
- #
1050
- # ===Synopsis(Chart)
1051
- #
1052
- # To create a simple Excel file with a chart using WriteExcel:
1053
- #
1054
- # #!/usr/bin/ruby -w
1055
- #
1056
- # require 'writeexcel'
1057
- #
1058
- # workbook = WriteExcel.new('chart.xls')
1059
- # worksheet = workbook.add_worksheet
1060
- #
1061
- # chart = workbook.add_chart(:type => 'Chart::Column')
1062
- #
1063
- # # Configure the chart.
1064
- # chart.add_series(
1065
- # :categories => '=Sheet1!$A$2:$A$7',
1066
- # :values => '=Sheet1!$B$2:$B$7'
1067
- # )
1068
- #
1069
- # # Add the data to the worksheet the chart refers to.
1070
- # data = [
1071
- # [ 'Category', 2, 3, 4, 5, 6, 7 ],
1072
- # [ 'Value', 1, 4, 5, 2, 1, 5 ]
1073
- # ]
1074
- #
1075
- # worksheet.write('A1', data)
1076
- #
1077
- # workbook.close
1078
- #
1079
- # ===DESCRIPTION(Chart)
1080
- #
1081
- # The Chart module is an abstract base class for modules that implement charts
1082
- # in WriteExcel. The information below is applicable to all of the available
1083
- # subclasses.
1084
- #
1085
- # The Chart module isn't used directly, a chart object is created via the
1086
- # Workbook add_chart() method where the chart type is specified:
1087
- #
1088
- # chart = workbook.add_chart(:type => 'Chart::Column')
1089
- #
1090
- # Currently the supported chart types are:
1091
- #
1092
- # * 'Chart::Column': Creates a column style (histogram) chart. See Column.
1093
- # * 'Chart::Bar': Creates a Bar style (transposed histogram) chart. See Bar.
1094
- # * 'Chart::Line': Creates a Line style chart. See Line.
1095
- # * 'Chart::Area': Creates an Area (filled line) style chart. See Area.
1096
- # * 'Chart::Scatter': Creates an Scatter style chart. See Scatter.
1097
- # * 'Chart::Stock': Creates an Stock style chart. See Stock.
1098
- #
1099
- # More chart types will be supported in time. See the "TODO" section.
1100
- #
1101
- # === Chart names and links
1102
- #
1103
- # The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
1104
- # support a name property. In general these names can be either a static
1105
- # string or a link to a worksheet cell. If you choose to use the name_formula
1106
- # property to specify a link then you should also the name property.
1107
- # This isn't strictly required by Excel but some third party applications
1108
- # expect it to be present.
1109
- #
1110
- # chartl.set_title(
1111
- # :name => 'Year End Results',
1112
- # :name_formula => '=Sheet1!$C$1'
1113
- # )
1114
- #
1115
- # These links should be used sparingly since they aren't commonly
1116
- # used in Excel charts.
1117
- #
1118
- # === Chart names and Unicode
1119
- #
1120
- # The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
1121
- # support a name property. These names can be UTF8 strings.
1122
- #
1123
- # This methodology is explained in the "UNICODE IN EXCEL" section of WriteExcel
1124
- # but is semi-deprecated. If you are using Unicode the easiest option is to
1125
- # just use UTF8.
1126
- #
1127
- # === TODO(Chart)
1128
- #
1129
- # Charts in WriteExcel are a work in progress. More chart types and
1130
- # features will be added in time. Please be patient. Even a small feature
1131
- # can take a week or more to implement, test and document.
1132
- #
1133
- # Features that are on the TODO list and will be added are:
1134
- #
1135
- # * Additional chart types. Stock, Pie and Scatter charts are next in line.
1136
- # Send an email if you are interested in other types and they will be
1137
- # added to the queue.
1138
- # * Colours and formatting options. For now you will have to make do
1139
- # with the default Excel colours and formats.
1140
- # * Axis controls, gridlines.
1141
- # * Embedded data in charts for third party application support.
1142
- #
1143
- # == KNOWN ISSUES(Chart)
1144
- #
1145
- # * Currently charts don't contain embedded data from which the charts
1146
- # can be rendered. Excel and most other third party applications ignore
1147
- # this and read the data via the links that have been specified. However,
1148
- # some applications may complain or not render charts correctly. The
1149
- # preview option in Mac OS X is an known example. This will be fixed
1150
- # in a later release.
1151
- # * When there are several charts with titles set in a workbook some of
1152
- # the titles may display at a font size of 10 instead of the default
1153
- # 12 until another chart with the title set is viewed.
1154
- #
1155
- class WriteExcel < Workbook
1156
- if RUBY_VERSION < '1.9'
1157
- $KCODE = 'u'
1158
- end
1159
- end
1
+ # -*- coding: utf-8 -*-
2
+ ###############################################################################
3
+ #
4
+ # WriteExcel.
5
+ #
6
+ # WriteExcel - Write to a cross-platform Excel binary file.
7
+ #
8
+ # Copyright 2000-2010, John McNamara, jmcnamara@cpan.org
9
+ #
10
+ # original written in Perl by John McNamara
11
+ # converted to Ruby by Hideo Nakamura, cxn03651@msj.biglobe.ne.jp
12
+ #
13
+ require 'writeexcel/biffwriter'
14
+ require 'writeexcel/olewriter'
15
+ require 'writeexcel/formula'
16
+ require 'writeexcel/format'
17
+ require 'writeexcel/worksheet'
18
+ require "writeexcel/workbook"
19
+ require 'writeexcel/chart'
20
+ require 'writeexcel/charts/area'
21
+ require 'writeexcel/charts/bar'
22
+ require 'writeexcel/charts/column'
23
+ require 'writeexcel/charts/external'
24
+ require 'writeexcel/charts/line'
25
+ require 'writeexcel/charts/pie'
26
+ require 'writeexcel/charts/scatter'
27
+ require 'writeexcel/charts/stock'
28
+ require 'writeexcel/storage_lite'
29
+ require 'writeexcel/compatibility'
30
+ require 'writeexcel/debug_info'
31
+ #
32
+ # = WriteExcel - Write to a cross-platform Excel binary file.
33
+ #
34
+ # == Contents
35
+ # SYSNOPSYS
36
+ # DESCRIPTION
37
+ # QUICK START
38
+ # WORKBOOK METHODS
39
+ # WORKSHEET METHODS
40
+ # PAGE SET-UP METHODS
41
+ # CELL FORMATTING
42
+ # FORMAT METHODS
43
+ # COLOURS IN EXCEL
44
+ # DATE AND TIME IN EXCEL
45
+ # OUTLINES AND GROUPING IN EXCEL
46
+ # DATA VALIDATION IN EXCEL
47
+ # FORMULAS AND FUNCTIONS IN EXCEL
48
+ # CHART
49
+ #
50
+ # == Synopsis
51
+ #
52
+ # To write a string, a formatted string, a number and a formula to the first
53
+ # worksheet in an Excel workbook called ruby.xls:
54
+ #
55
+ # require 'WriteExcel'
56
+ #
57
+ # # Create a new Excel workbook
58
+ # workbook = WriteExcel.new('ruby.xls')
59
+ #
60
+ # # Add a worksheet
61
+ # worksheet = workbook.add_worksheet
62
+ #
63
+ # # Add and define a format
64
+ # format = workbook.add_format # Add a format
65
+ # format.set_bold()
66
+ # format.set_color('red')
67
+ # format.set_align('center')
68
+ #
69
+ # # Write a formatted and unformatted string, row and column notation.
70
+ # col = row = 0
71
+ # worksheet.write(row, col, 'Hi Excel!', format)
72
+ # worksheet.write(1, col, 'Hi Excel!')
73
+ #
74
+ # # Write a number and a formula using A1 notation
75
+ # worksheet.write('A3', 1.2345)
76
+ # worksheet.write('A4', '=SIN(PI()/4)')
77
+ #
78
+ # # Save to ruby.xls
79
+ # workbook.close
80
+ #
81
+ # == Description
82
+ #
83
+ # WriteExcel can be used to create a cross-platform Excel binary file.
84
+ # Multiple worksheets can be added to a workbook and formatting can be applied
85
+ # to cells. Text, numbers, formulas, hyperlinks and images can be written to
86
+ # the cells.
87
+ #
88
+ # The Excel file produced by this gem is compatible with 97, 2000, 2002, 2003
89
+ # and 2007.
90
+ #
91
+ # WriteExcel will work on the majority of Windows, UNIX and Mac platforms.
92
+ # Generated files are also compatible with the Linux/UNIX spreadsheet
93
+ # applications Gnumeric and OpenOffice.org.
94
+ #
95
+ # This module cannot be used to write to an existing Excel file
96
+ #
97
+ # This library is converted from Spreadsheet::WriteExcel module of Perl.
98
+ # http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel-2.37/
99
+ #
100
+ # == Quick Start
101
+ #
102
+ # WriteExcel tries to provide an interface to as many of Excel's features as
103
+ # possible. As a result there is a lot of documentation to accompany the
104
+ # interface and it can be difficult at first glance to see what it important
105
+ # and what is not. So for those of you who prefer to assemble Ikea furniture
106
+ # first and then read the instructions, here are four easy steps:
107
+ #
108
+ # 1. Create a new Excel workbook (i.e. file) using new().
109
+ #
110
+ # 2. Add a worksheet to the new workbook using add_worksheet().
111
+ #
112
+ # 3. Write to the worksheet using write().
113
+ #
114
+ # 4. Save to file.
115
+ #
116
+ # Like this:
117
+ #
118
+ # require 'WriteExcel' # Step 0
119
+ #
120
+ # workbook = WriteExcel.new('ruby.xls') # Step 1
121
+ # worksheet = workbook.add_worksheet # Step 2
122
+ # worksheet.write('A1', 'Hi Excel!') # Step 3
123
+ # workbook.close # Step 4
124
+ #
125
+ # This will create an Excel file called ruby.xls with a single worksheet and the
126
+ # text 'Hi Excel!' in the relevant cell. And that's it. Okay, so there is
127
+ # actually a zeroth step as well, but use WriteExcel goes without saying. There
128
+ # are also many examples that come with the distribution and which you can
129
+ # use to get you started. See EXAMPLES.
130
+ #
131
+ # = Workbook methods
132
+ #
133
+ # The WriteExcel module provides an object oriented interface
134
+ # to a new Excel workbook. The following methods are available through
135
+ # a new workbook.
136
+ #
137
+ # new()
138
+ # add_worksheet()
139
+ # add_format()
140
+ # add_chart()
141
+ # add_chart_ext()
142
+ # close()
143
+ # compatibility_mode()
144
+ # set_properties()
145
+ # define_name()
146
+ # set_tempdir()
147
+ # set_custom_color()
148
+ # sheets()
149
+ # set_1904()
150
+ # set_codepage()
151
+ #
152
+ # = Worksheet methods
153
+ #
154
+ # A new worksheet is created by calling the add_worksheet() method from
155
+ # a workbook object:
156
+ #
157
+ # worksheet1 = workbook.add_worksheet
158
+ # worksheet2 = workbook.add_worksheet
159
+ #
160
+ # The following methods are available through a new worksheet:
161
+ #
162
+ # write()
163
+ # write_number()
164
+ # write_string()
165
+ # write_utf16be_string()
166
+ # write_utf16le_string()
167
+ # keep_leading_zeros()
168
+ # write_blank()
169
+ # write_row()
170
+ # write_col()
171
+ # write_date_time()
172
+ # write_url()
173
+ # write_url_range()
174
+ # write_formula()
175
+ # store_formula()
176
+ # repeat_formula()
177
+ # write_comment()
178
+ # show_comments()
179
+ # add_write_handler() (* not implemented yet)
180
+ # insert_image()
181
+ # insert_chart()
182
+ # data_validation()
183
+ # get_name()
184
+ # activate()
185
+ # select()
186
+ # hide()
187
+ # set_first_sheet()
188
+ # protect()
189
+ # set_selection()
190
+ # set_row()
191
+ # set_column()
192
+ # outline_settings()
193
+ # freeze_panes()
194
+ # split_panes()
195
+ # merge_range()
196
+ # set_zoom()
197
+ # right_to_left()
198
+ # hide_zero()
199
+ # set_tab_color()
200
+ # autofilter()
201
+ #
202
+ # == Cell notation
203
+ # WriteExcel supports two forms of notation to designate the position of cells:
204
+ # Row-column notation and A1 notation.
205
+ #
206
+ # Row-column notation uses a zero based index for both row and column while A1
207
+ # notation uses the standard Excel alphanumeric sequence of column letter and
208
+ # 1-based row. For example:
209
+ #
210
+ # (0, 0) # The top left cell in row-column notation.
211
+ # ('A1') # The top left cell in A1 notation.
212
+ #
213
+ # (1999, 29) # Row-column notation.
214
+ # ('AD2000') # The same cell in A1 notation.
215
+ #
216
+ # Row-column notation is useful if you are referring to cells
217
+ # programmatically:
218
+ #
219
+ # (0 .. 10).each do |i|
220
+ # worksheet.write(i, 0, 'Hello') # Cells A1 to A10
221
+ # end
222
+ #
223
+ # A1 notation is useful for setting up a worksheet manually and for working
224
+ # with formulas:
225
+ #
226
+ # worksheet.write('H1', 200)
227
+ # worksheet.write('H2', '=H1+1')
228
+ #
229
+ # In formulas and applicable methods you can also use the A:A column notation:
230
+ #
231
+ # worksheet.write('A1', '=SUM(B:B)')
232
+ #
233
+ # For simplicity, the parameter lists for the worksheet method calls in the
234
+ # following sections are given in terms of row-column notation. In all cases
235
+ # it is also possible to use A1 notation.
236
+ #
237
+ # Note: in Excel it is also possible to use a R1C1 notation. This is not
238
+ # supported by WriteExcel.
239
+ #
240
+ # ==PAGE SET-UP METHODS
241
+ #
242
+ # Page set-up methods affect the way that a worksheet looks when it is printed.
243
+ # They control features such as page headers and footers and margins. These
244
+ # methods are really just standard worksheet methods. They are documented
245
+ # here in a separate section for the sake of clarity.
246
+ #
247
+ # The following methods are available for page set-up:
248
+ #
249
+ # set_landscape()
250
+ # set_portrait()
251
+ # set_page_view()
252
+ # set_paper()
253
+ # center_horizontally()
254
+ # center_vertically()
255
+ # set_margins()
256
+ # set_header()
257
+ # set_footer()
258
+ # repeat_rows()
259
+ # repeat_columns()
260
+ # hide_gridlines()
261
+ # print_row_col_headers()
262
+ # print_area()
263
+ # print_across()
264
+ # fit_to_pages()
265
+ # set_start_page()
266
+ # set_print_scale()
267
+ # set_h_pagebreaks()
268
+ # set_v_pagebreaks()
269
+ #
270
+ # A common requirement when working with WriteExcel is to apply the same page
271
+ # set-up features to all of the worksheets in a workbook. To do this you can use
272
+ # the sheets() method of the workbook class to access the array of worksheets
273
+ # in a workbook:
274
+ #
275
+ # workbook.sheets.each do |worksheet|
276
+ # worksheet.set_landscape
277
+ # end
278
+ #
279
+ # ==CELL FORMATTING
280
+ #
281
+ # This section describes the methods and properties that are available for
282
+ # formatting cells in Excel. The properties of a cell that can be formatted
283
+ # include: fonts, colours, patterns, borders, alignment and number formatting.
284
+ #
285
+ # ===Creating and using a Format object
286
+ #
287
+ # Cell formatting is defined through a Format object. Format objects are
288
+ # created by calling the workbook add_format() method as follows:
289
+ #
290
+ # format1 = workbook.add_format # Set properties later
291
+ # format2 = workbook.add_format(property hash..) # Set at creation
292
+ #
293
+ # The format object holds all the formatting properties that can be applied
294
+ # to a cell, a row or a column. The process of setting these properties is
295
+ # discussed in the next section.
296
+ #
297
+ # Once a Format object has been constructed and it properties have been set
298
+ # it can be passed as an argument to the worksheet write methods as follows:
299
+ #
300
+ # worksheet.write(0, 0, 'One', format)
301
+ # worksheet.write_string(1, 0, 'Two', format)
302
+ # worksheet.write_number(2, 0, 3, format)
303
+ # worksheet.write_blank(3, 0, format)
304
+ #
305
+ # Formats can also be passed to the worksheet set_row() and set_column()
306
+ # methods to define the default property for a row or column.
307
+ #
308
+ # worksheet.set_row(0, 15, format)
309
+ # worksheet.set_column(0, 0, 15, format)
310
+ #
311
+ # ===Format methods and Format properties
312
+ #
313
+ # The following table shows the Excel format categories, the formatting
314
+ # properties that can be applied and the equivalent object method:
315
+ #
316
+ # Category Description Property Method Name
317
+ # -------- ----------- -------- -----------
318
+ # Font Font type font set_font()
319
+ # Font size size set_size()
320
+ # Font color color set_color()
321
+ # Bold bold set_bold()
322
+ # Italic italic set_italic()
323
+ # Underline underline set_underline()
324
+ # Strikeout font_strikeout set_font_strikeout()
325
+ # Super/Subscript font_script set_font_script()
326
+ # Outline font_outline set_font_outline()
327
+ # Shadow font_shadow set_font_shadow()
328
+ #
329
+ # Number Numeric format num_format set_num_format()
330
+ #
331
+ # Protection Lock cells locked set_locked()
332
+ # Hide formulas hidden set_hidden()
333
+ #
334
+ # Alignment Horizontal align align set_align()
335
+ # Vertical align valign set_align()
336
+ # Rotation rotation set_rotation()
337
+ # Text wrap text_wrap set_text_wrap()
338
+ # Justify last text_justlast set_text_justlast()
339
+ # Center across center_across set_center_across()
340
+ # Indentation indent set_indent()
341
+ # Shrink to fit shrink set_shrink()
342
+ #
343
+ # Pattern Cell pattern pattern set_pattern()
344
+ # Background color bg_color set_bg_color()
345
+ # Foreground color fg_color set_fg_color()
346
+ #
347
+ # Border Cell border border set_border()
348
+ # Bottom border bottom set_bottom()
349
+ # Top border top set_top()
350
+ # Left border left set_left()
351
+ # Right border right set_right()
352
+ # Border color border_color set_border_color()
353
+ # Bottom color bottom_color set_bottom_color()
354
+ # Top color top_color set_top_color()
355
+ # Left color left_color set_left_color()
356
+ # Right color right_color set_right_color()
357
+ #
358
+ # There are two ways of setting Format properties: by using the object method
359
+ # interface or by setting the property directly. For example, a typical use of
360
+ # the method interface would be as follows:
361
+ #
362
+ # format = workbook.add_format
363
+ # format.set_bold
364
+ # format.set_color('red')
365
+ #
366
+ # By comparison the properties can be set directly by passing a hash of
367
+ # properties to the Format constructor:
368
+ #
369
+ # format = workbook.add_format(:bold => 1, :color => 'red')
370
+ #
371
+ # or after the Format has been constructed by means of the
372
+ # set_format_properties() method as follows:
373
+ #
374
+ # format = workbook.add_format
375
+ # format.set_format_properties(:bold => 1, :color => 'red')
376
+ #
377
+ # You can also store the properties in one or more named hashes and pass them
378
+ # to the required method:
379
+ #
380
+ # font = {
381
+ # :font => 'Arial',
382
+ # :size => 12,
383
+ # :color => 'blue',
384
+ # :bold => 1
385
+ # }
386
+ #
387
+ # shading = {
388
+ # :bg_color => 'green',
389
+ # :pattern => 1
390
+ # }
391
+ #
392
+ # format1 = workbook.add_format(font) # Font only
393
+ # format2 = workbook.add_format(font, shading) # Font and shading
394
+ #
395
+ # The provision of two ways of setting properties might lead you to wonder
396
+ # which is the best way. The method mechanism may be better is you prefer
397
+ # setting properties via method calls (which the author did when they were
398
+ # code was first written) otherwise passing properties to the constructor has
399
+ # proved to be a little more flexible and self documenting in practice. An
400
+ # additional advantage of working with property hashes is that it allows you to
401
+ # share formatting between workbook objects as shown in the example above.
402
+ #
403
+ #--
404
+ #
405
+ # did not converted ???
406
+ #
407
+ # The Perl/Tk style of adding properties is also supported:
408
+ #
409
+ # %font = (
410
+ # -font => 'Arial',
411
+ # -size => 12,
412
+ # -color => 'blue',
413
+ # -bold => 1,
414
+ # )
415
+ #++
416
+ #
417
+ # ===Working with formats
418
+ #
419
+ # The default format is Arial 10 with all other properties off.
420
+ #
421
+ # Each unique format in WriteExcel must have a corresponding
422
+ # Format object. It isn't possible to use a Format with a write() method and
423
+ # then redefine the Format for use at a later stage. This is because a Format
424
+ # is applied to a cell not in its current state but in its final state.
425
+ # Consider the following example:
426
+ #
427
+ # format = workbook.add_format
428
+ # format.set_bold
429
+ # format.set_color('red')
430
+ # worksheet.write('A1', 'Cell A1', format)
431
+ # format.set_color('green')
432
+ # worksheet.write('B1', 'Cell B1', format)
433
+ #
434
+ # Cell A1 is assigned the Format _format_ which is initially set to the colour
435
+ # red. However, the colour is subsequently set to green. When Excel displays
436
+ # Cell A1 it will display the final state of the Format which in this case
437
+ # will be the colour green.
438
+ #
439
+ # In general a method call without an argument will turn a property on,
440
+ # for example:
441
+ #
442
+ # format1 = workbook.add_format
443
+ # format1.set_bold # Turns bold on
444
+ # format1.set_bold(1) # Also turns bold on
445
+ # format1.set_bold(0) # Turns bold off
446
+ #
447
+ # ==FORMAT METHODS
448
+ #
449
+ # The Format object methods are described in more detail in the following
450
+ # sections. In addition, there is a Ruby program called formats.rb in the
451
+ # examples directory of the WriteExcel distribution. This program creates an
452
+ # Excel workbook called formats.xls which contains examples of almost all
453
+ # the format types.
454
+ #
455
+ # The following Format methods are available:
456
+ #
457
+ # set_font()
458
+ # set_size()
459
+ # set_color()
460
+ # set_bold()
461
+ # set_italic()
462
+ # set_underline()
463
+ # set_font_strikeout()
464
+ # set_font_script()
465
+ # set_font_outline()
466
+ # set_font_shadow()
467
+ # set_num_format()
468
+ # set_locked()
469
+ # set_hidden()
470
+ # set_align()
471
+ # set_rotation()
472
+ # set_text_wrap()
473
+ # set_text_justlast()
474
+ # set_center_across()
475
+ # set_indent()
476
+ # set_shrink()
477
+ # set_pattern()
478
+ # set_bg_color()
479
+ # set_fg_color()
480
+ # set_border()
481
+ # set_bottom()
482
+ # set_top()
483
+ # set_left()
484
+ # set_right()
485
+ # set_border_color()
486
+ # set_bottom_color()
487
+ # set_top_color()
488
+ # set_left_color()
489
+ # set_right_color()
490
+ #
491
+ # The above methods can also be applied directly as properties. For example
492
+ # format.set_bold is equivalent to workbook.add_format(:bold => 1).
493
+ #
494
+ # ==COLOURS IN EXCEL
495
+ #
496
+ # Excel provides a colour palette of 56 colours. In WriteExcel these colours
497
+ # are accessed via their palette index in the range 8..63. This index is used
498
+ # to set the colour of fonts, cell patterns and cell borders. For example:
499
+ #
500
+ # format = workbook.add_format(
501
+ # :color => 12, # index for blue
502
+ # :font => 'Arial',
503
+ # :size => 12,
504
+ # :bold => 1
505
+ # )
506
+ #
507
+ # The most commonly used colours can also be accessed by name. The name acts
508
+ # as a simple alias for the colour index:
509
+ #
510
+ # black => 8
511
+ # blue => 12
512
+ # brown => 16
513
+ # cyan => 15
514
+ # gray => 23
515
+ # green => 17
516
+ # lime => 11
517
+ # magenta => 14
518
+ # navy => 18
519
+ # orange => 53
520
+ # pink => 33
521
+ # purple => 20
522
+ # red => 10
523
+ # silver => 22
524
+ # white => 9
525
+ # yellow => 13
526
+ #
527
+ # For example:
528
+ #
529
+ # font = workbook.add_format(:color => 'red')
530
+ #
531
+ # Users of VBA in Excel should note that the equivalent colour indices are in
532
+ # the range 1..56 instead of 8..63.
533
+ #
534
+ # If the default palette does not provide a required colour you can override
535
+ # one of the built-in values. This is achieved by using the set_custom_color()
536
+ # workbook method to adjust the RGB (red green blue) components of the colour:
537
+ #
538
+ # ferrari = workbook.set_custom_color(40, 216, 12, 12)
539
+ #
540
+ # format = workbook.add_format(
541
+ # :bg_color => ferrari,
542
+ # :pattern => 1,
543
+ # :border => 1
544
+ # )
545
+ #
546
+ # worksheet.write_blank('A1', format)
547
+ #
548
+ # You may also find the following links helpful:
549
+ #
550
+ # A detailed look at Excel's colour palette:
551
+ # http://www.mvps.org/dmcritchie/excel/colors.htm
552
+ #
553
+ # A decimal RGB chart: http://www.hypersolutions.org/pages/rgbdec.html
554
+ #
555
+ # A hex RGB chart: : http://www.hypersolutions.org/pages/rgbhex.html
556
+ #
557
+ # ==DATES AND TIME IN EXCEL
558
+ #
559
+ # There are two important things to understand about dates and times in Excel:
560
+ #
561
+ # 1. A date/time in Excel is a real number plus an Excel number format.
562
+ #
563
+ # 2. WriteExcel doesn't automatically convert date/time strings in write() to
564
+ # an Excel date/time.
565
+ #
566
+ # These two points are explained in more detail below along with some
567
+ # suggestions on how to convert times and dates to the required format.
568
+ #
569
+ # ===An Excel date/time is a number plus a format
570
+ #
571
+ # If you write a date string with write() then all you will get is a string:
572
+ #
573
+ # worksheet.write('A1', '02/03/04') # !! Writes a string not a date. !!
574
+ #
575
+ # Dates and times in Excel are represented by real numbers, for example
576
+ # "Jan 1 2001 12:30 AM" is represented by the number 36892.521.
577
+ #
578
+ # The integer part of the number stores the number of days since the epoch
579
+ # and the fractional part stores the percentage of the day.
580
+ #
581
+ # A date or time in Excel is just like any other number. To have the number
582
+ # display as a date you must apply an Excel number format to it. Here are
583
+ # some examples.
584
+ #
585
+ # #!/usr/bin/ruby -w
586
+ #
587
+ # require 'writeexcel'
588
+ #
589
+ # workbook = WriteExcel.new('date_examples.xls')
590
+ # worksheet = workbook.add_worksheet
591
+ #
592
+ # worksheet.set_column('A:A', 30) # For extra visibility.
593
+ #
594
+ # number = 39506.5
595
+ #
596
+ # worksheet.write('A1', number) # 39506.5
597
+ #
598
+ # format2 = workbook.add_format(:num_format => 'dd/mm/yy')
599
+ # worksheet.write('A2', number , format2); # 28/02/08
600
+ #
601
+ # format3 = workbook.add_format(:num_format => 'mm/dd/yy')
602
+ # worksheet.write('A3', number , format3); # 02/28/08
603
+ #
604
+ # format4 = workbook.add_format(:num_format => 'd-m-yyyy')
605
+ # worksheet.write('A4', .number , format4) # 28-2-2008
606
+ #
607
+ # format5 = workbook.add_format(:num_format => 'dd/mm/yy hh:mm')
608
+ # worksheet.write('A5', number , format5) # 28/02/08 12:00
609
+ #
610
+ # format6 = workbook.add_format(:num_format => 'd mmm yyyy')
611
+ # worksheet.write('A6', number , format6) # 28 Feb 2008
612
+ #
613
+ # format7 = workbook.add_format(:num_format => 'mmm d yyyy hh:mm AM/PM')
614
+ # worksheet.write('A7', number , format7) # Feb 28 2008 12:00 PM
615
+ #
616
+ # ===WriteExcel doesn't automatically convert date/time strings
617
+ #
618
+ # WriteExcel doesn't automatically convert input date strings into Excel's
619
+ # formatted date numbers due to the large number of possible date formats
620
+ # and also due to the possibility of misinterpretation.
621
+ #
622
+ # For example, does 02/03/04 mean March 2 2004, February 3 2004 or even March
623
+ # 4 2002.
624
+ #
625
+ # Therefore, in order to handle dates you will have to convert them to numbers
626
+ # and apply an Excel format. Some methods for converting dates are listed in
627
+ # the next section.
628
+ #
629
+ # The most direct way is to convert your dates to the ISO8601
630
+ # yyyy-mm-ddThh:mm:ss.sss date format and use the write_date_time() worksheet
631
+ # method:
632
+ #
633
+ # worksheet.write_date_time('A2', '2001-01-01T12:20', format)
634
+ #
635
+ # See the write_date_time() section of the documentation for more details.
636
+ #
637
+ # A general methodology for handling date strings with write_date_time() is:
638
+ #
639
+ # 1. Identify incoming date/time strings with a regex.
640
+ # 2. Extract the component parts of the date/time using the same regex.
641
+ # 3. Convert the date/time to the ISO8601 format.
642
+ # 4. Write the date/time using write_date_time() and a number format.
643
+ #
644
+ # Here is an example:
645
+ #
646
+ # #!/usr/bin/ruby -w
647
+ #
648
+ # require 'writeexcel'
649
+ #
650
+ # workbook = WriteExcel.new('example.xls')
651
+ # worksheet = workbook.add_worksheet
652
+ #
653
+ # # Set the default format for dates.
654
+ # date_format = workbook.add_format(:num_format => 'mmm d yyyy')
655
+ #
656
+ # # Increase column width to improve visibility of data.
657
+ # worksheet.set_column('A:C', 20)
658
+ #
659
+ # data = [
660
+ # %w(Item Cost Date),
661
+ # %w(Book 10 1/9/2007),
662
+ # %w(Beer 4 12/9/2007),
663
+ # %w(Bed 500 5/10/2007)
664
+ # ]
665
+ #
666
+ # # Simulate reading from a data source.
667
+ # row = 0
668
+ #
669
+ # data.each do |row_data|
670
+ # col = 0
671
+ # row_data.each do |item|
672
+ #
673
+ # # Match dates in the following formats: d/m/yy, d/m/yyyy
674
+ # if item =~ %r[^(\d{1,2})/(\d{1,2})/(\d{4})$]
675
+ # # Change to the date format required by write_date_time().
676
+ # date = sprintf "%4d-%02d-%02dT", $3, $2, $1
677
+ # worksheet.write_date_time(row, col, date, date_format)
678
+ # else
679
+ # # Just plain data
680
+ # worksheet.write(row, col, item)
681
+ # end
682
+ # col += 1
683
+ # end
684
+ # row += 1
685
+ # end
686
+ #
687
+ #--
688
+ # For a slightly more advanced solution you can modify the write() method to
689
+ # handle date formats of your choice via the add_write_handler() method. See
690
+ # the add_write_handler() section of the docs and the write_handler3.rb and
691
+ # write_handler4.rb programs in the examples directory of the distro.
692
+ #++
693
+ #
694
+ # ==OUTLINES AND GROUPING IN EXCEL
695
+ #
696
+ # Excel allows you to group rows or columns so that they can be hidden or
697
+ # displayed with a single mouse click. This feature is referred to as outlines.
698
+ #
699
+ # Outlines can reduce complex data down to a few salient sub-totals or
700
+ # summaries.
701
+ #
702
+ # This feature is best viewed in Excel but the following is an ASCII
703
+ # representation of what a worksheet with three outlines might look like. Rows
704
+ # 3-4 and rows 7-8 are grouped at level 2. Rows 2-9 are grouped at level 1.
705
+ # The lines at the left hand side are called outline level bars.
706
+ #
707
+ # ------------------------------------------
708
+ # 1 2 3 | | A | B | C | D | ...
709
+ # ------------------------------------------
710
+ # _ | 1 | A | | | | ...
711
+ # | _ | 2 | B | | | | ...
712
+ # | | | 3 | (C) | | | | ...
713
+ # | | | 4 | (D) | | | | ...
714
+ # | - | 5 | E | | | | ...
715
+ # | _ | 6 | F | | | | ...
716
+ # | | | 7 | (G) | | | | ...
717
+ # | | | 8 | (H) | | | | ...
718
+ # | - | 9 | I | | | | ...
719
+ # - | . | ... | ... | ... | ... | ...
720
+ #
721
+ # Clicking the minus sign on each of the level 2 outlines will collapse and
722
+ # hide the data as shown in the next figure. The minus sign changes to a plus
723
+ # sign to indicate that the data in the outline is hidden.
724
+ #
725
+ # ------------------------------------------
726
+ # 1 2 3 | | A | B | C | D | ...
727
+ # ------------------------------------------
728
+ # _ | 1 | A | | | | ...
729
+ # | | 2 | B | | | | ...
730
+ # | + | 5 | E | | | | ...
731
+ # | | 6 | F | | | | ...
732
+ # | + | 9 | I | | | | ...
733
+ # - | . | ... | ... | ... | ... | ...
734
+ #
735
+ # Clicking on the minus sign on the level 1 outline will collapse the
736
+ # remaining rows as follows:
737
+ #
738
+ # ------------------------------------------
739
+ # 1 2 3 | | A | B | C | D | ...
740
+ # ------------------------------------------
741
+ # | 1 | A | | | | ...
742
+ # + | . | ... | ... | ... | ... | ...
743
+ #
744
+ # Grouping in WriteExcel is achieved by setting the outline level via the
745
+ # set_row() and set_column() worksheet methods:
746
+ #
747
+ # set_row(row, height, format, hidden, level, collapsed)
748
+ # set_column(first_col, last_col, width, format, hidden, level, collapsed)
749
+ #
750
+ # The following example sets an outline level of 1 for rows 1 and 2
751
+ # (zero-indexed) and columns B to G. The parameters _height_ and _format_ are
752
+ # assigned default values since they are undefined:
753
+ #
754
+ # worksheet.set_row(1, nil, nil, 0, 1)
755
+ # worksheet.set_row(2, nil, nil, 0, 1)
756
+ # worksheet.set_column('B:G', nil, nil, 0, 1)
757
+ #
758
+ # Excel allows up to 7 outline levels. Therefore the _level_ parameter should
759
+ # be in the range 0 <= _level_ <= 7.
760
+ #
761
+ # Rows and columns can be collapsed by setting the _hidden_ flag for the hidden
762
+ # rows/columns and setting the _collapsed_ flag for the row/column that has
763
+ # the collapsed + symbol:
764
+ #
765
+ # worksheet.set_row(1, nil, nil, 1, 1)
766
+ # worksheet.set_row(2, nil, nil, 1, 1)
767
+ # worksheet.set_row(3, nil, nil, 0, 0, 1) # Collapsed flag.
768
+ #
769
+ # worksheet.set_column('B:G', nil, nil, 1, 1)
770
+ # worksheet.set_column('H:H', nil, nil, 0, 0, 1) # Collapsed flag.
771
+ #
772
+ # Note: Setting the _collapsed_ flag is particularly important for
773
+ # compatibility with OpenOffice.org and Gnumeric.
774
+ #
775
+ # For a more complete example see the outline.rb
776
+ # and outline_collapsed.rb
777
+ # programs in the examples directory of the distro.
778
+ #
779
+ # Some additional outline properties can be set via the outline_settings()
780
+ # worksheet method, see above.
781
+ #
782
+ # ==DATA VALIDATION IN EXCEL
783
+ #
784
+ # Data validation is a feature of Excel which allows you to restrict the data
785
+ # that a users enters in a cell and to display help and warning messages. It
786
+ # also allows you to restrict input to values in a drop down list.
787
+ #
788
+ # A typical use case might be to restrict data in a cell to integer values in
789
+ # a certain range, to provide a help message to indicate the required value and
790
+ # to issue a warning if the input data doesn't meet the stated criteria.
791
+ # In WriteExcel we could do that as follows:
792
+ #
793
+ # worksheet.data_validation('B3',
794
+ # {
795
+ # :validate => 'integer',
796
+ # :criteria => 'between',
797
+ # :minimum => 1,
798
+ # :maximum => 100,
799
+ # :input_title => 'Input an integer:',
800
+ # :input_message => 'Between 1 and 100',
801
+ # :error_message => 'Sorry, try again.'
802
+ # })
803
+ #
804
+ # The above example would look like this in Excel:
805
+ # http://homepage.eircom.net/~jmcnamara/perl/data_validation.jpg.
806
+ #
807
+ # For more information on data validation see the following Microsoft
808
+ # support article "Description and examples of data validation in Excel":
809
+ # http://support.microsoft.com/kb/211485.
810
+ #
811
+ # ==FORMULAS AND FUNCTIONS IN EXCEL
812
+ #
813
+ # ===Caveats
814
+ #
815
+ # The first thing to note is that there are still some outstanding issues
816
+ # with the implementation of formulas and functions:
817
+ #
818
+ # 1. Writing a formula is much slower than writing the equivalent string.
819
+ # 2. You cannot use array constants, i.e. {1;2;3}, in functions.
820
+ # 3. Unary minus isn't supported.
821
+ # 4. Whitespace is not preserved around operators.
822
+ # 5. Named ranges are not supported.
823
+ # 6. Array formulas are not supported.
824
+ #
825
+ # However, these constraints will be removed in future versions. They are
826
+ # here because of a trade-off between features and time. Also, it is possible
827
+ # to work around issue 1 using the store_formula() and repeat_formula()
828
+ # methods as described later in this section.
829
+ #
830
+ # ===Introduction
831
+ #
832
+ # The following is a brief introduction to formulas and functions in Excel
833
+ # and WriteExcel.
834
+ #
835
+ # A formula is a string that begins with an equals sign:
836
+ #
837
+ # '=A1+B1'
838
+ # '=AVERAGE(1, 2, 3)'
839
+ #
840
+ # The formula can contain numbers, strings, boolean values, cell references,
841
+ # cell ranges and functions. Named ranges are not supported. Formulas should
842
+ # be written as they appear in Excel, that is cells and functions must be
843
+ # in uppercase.
844
+ #
845
+ # Cells in Excel are referenced using the A1 notation system where the
846
+ # column is designated by a letter and the row by a number. Columns
847
+ # range from A to IV i.e. 0 to 255, rows range from 1 to 65536.
848
+ #--
849
+ # The WriteExcel::Utility module that is included in the distro
850
+ # contains helper functions for dealing with A1 notation, for example:
851
+ #
852
+ # use Spreadsheet::WriteExcel::Utility;
853
+ #
854
+ # ($row, $col) = xl_cell_to_rowcol('C2'); # (1, 2)
855
+ # $str = xl_rowcol_to_cell(1, 2); # C2
856
+ #++
857
+ #
858
+ # The Excel $ notation in cell references is also supported. This allows you
859
+ # to specify whether a row or column is relative or absolute. This only has
860
+ # an effect if the cell is copied. The following examples show relative and
861
+ # absolute values.
862
+ #
863
+ # '=A1' # Column and row are relative
864
+ # '=$A1' # Column is absolute and row is relative
865
+ # '=A$1' # Column is relative and row is absolute
866
+ # '=$A$1' # Column and row are absolute
867
+ #
868
+ # Formulas can also refer to cells in other worksheets of the current
869
+ # workbook. For example:
870
+ #
871
+ # '=Sheet2!A1'
872
+ # '=Sheet2!A1:A5'
873
+ # '=Sheet2:Sheet3!A1'
874
+ # '=Sheet2:Sheet3!A1:A5'
875
+ # q{='Test Data'!A1}
876
+ # q{='Test Data1:Test Data2'!A1}
877
+ #
878
+ # The sheet reference and the cell reference are separated by ! the exclamation
879
+ # mark symbol. If worksheet names contain spaces, commas o parentheses then Excel
880
+ # requires that the name is enclosed in single quotes as shown in the last two
881
+ # examples above. In order to avoid using a lot of escape characters you can
882
+ # use the quote operator %q{} to protect the quotes. Only valid sheet names that
883
+ # have been added using the add_worksheet() method can be used in formulas.
884
+ # You cannot reference external workbooks.
885
+ #
886
+ # The following table lists the operators that are available in Excel's formulas.
887
+ # The majority of the operators are the same as Perl's, differences are indicated:
888
+ #
889
+ # Arithmetic operators:
890
+ # =====================
891
+ # Operator Meaning Example
892
+ # + Addition 1+2
893
+ # - Subtraction 2-1
894
+ # * Multiplication 2*3
895
+ # / Division 1/4
896
+ # ^ Exponentiation 2^3 # Equivalent to **
897
+ # - Unary minus -(1+2) # Not yet supported
898
+ # % Percent (Not modulus) 13% # Not supported, [1]
899
+ #
900
+ # Comparison operators:
901
+ # =====================
902
+ # Operator Meaning Example
903
+ # = Equal to A1 = B1 # Equivalent to ==
904
+ # <> Not equal to A1 <> B1 # Equivalent to !=
905
+ # > Greater than A1 > B1
906
+ # < Less than A1 < B1
907
+ # >= Greater than or equal to A1 >= B1
908
+ # <= Less than or equal to A1 <= B1
909
+ #
910
+ # String operator:
911
+ # ================
912
+ # Operator Meaning Example
913
+ # & Concatenation "Hello " & "World!" # [2]
914
+ #
915
+ # Reference operators:
916
+ # ====================
917
+ # Operator Meaning Example
918
+ # : Range operator A1:A4 # [3]
919
+ # , Union operator SUM(1, 2+2, B3) # [4]
920
+ #
921
+ # Notes:
922
+ # [1]: You can get a percentage with formatting and modulus with MOD().
923
+ # [2]: Equivalent to ("Hello " . "World!") in Perl.
924
+ # [3]: This range is equivalent to cells A1, A2, A3 and A4.
925
+ # [4]: The comma behaves like the list separator in Perl.
926
+ #
927
+ # The range and comma operators can have different symbols in non-English
928
+ # versions of Excel. These will be supported in a later version of WriteExcel.
929
+ # European users of Excel take note:
930
+ #
931
+ # worksheet.write('A1', '=SUM(1; 2; 3)') # Wrong!!
932
+ # worksheet.write('A1', '=SUM(1, 2, 3)') # Okay
933
+ #
934
+ # The following table lists all of the core functions supported by
935
+ # Excel 5 and WriteExcel. Any additional functions that are available through
936
+ # the "Analysis ToolPak" or other add-ins are not supported. These functions
937
+ # have all been tested to verify that they work.
938
+ #
939
+ # ABS DB INDIRECT NORMINV SLN
940
+ # ACOS DCOUNT INFO NORMSDIST SLOPE
941
+ # ACOSH DCOUNTA INT NORMSINV SMALL
942
+ # ADDRESS DDB INTERCEPT NOT SQRT
943
+ # AND DEGREES IPMT NOW STANDARDIZE
944
+ # AREAS DEVSQ IRR NPER STDEV
945
+ # ASIN DGET ISBLANK NPV STDEVP
946
+ # ASINH DMAX ISERR ODD STEYX
947
+ # ATAN DMIN ISERROR OFFSET SUBSTITUTE
948
+ # ATAN2 DOLLAR ISLOGICAL OR SUBTOTAL
949
+ # ATANH DPRODUCT ISNA PEARSON SUM
950
+ # AVEDEV DSTDEV ISNONTEXT PERCENTILE SUMIF
951
+ # AVERAGE DSTDEVP ISNUMBER PERCENTRANK SUMPRODUCT
952
+ # BETADIST DSUM ISREF PERMUT SUMSQ
953
+ # BETAINV DVAR ISTEXT PI SUMX2MY2
954
+ # BINOMDIST DVARP KURT PMT SUMX2PY2
955
+ # CALL ERROR.TYPE LARGE POISSON SUMXMY2
956
+ # CEILING EVEN LEFT POWER SYD
957
+ # CELL EXACT LEN PPMT T
958
+ # CHAR EXP LINEST PROB TAN
959
+ # CHIDIST EXPONDIST LN PRODUCT TANH
960
+ # CHIINV FACT LOG PROPER TDIST
961
+ # CHITEST FALSE LOG10 PV TEXT
962
+ # CHOOSE FDIST LOGEST QUARTILE TIME
963
+ # CLEAN FIND LOGINV RADIANS TIMEVALUE
964
+ # CODE FINV LOGNORMDIST RAND TINV
965
+ # COLUMN FISHER LOOKUP RANK TODAY
966
+ # COLUMNS FISHERINV LOWER RATE TRANSPOSE
967
+ # COMBIN FIXED MATCH REGISTER.ID TREND
968
+ # CONCATENATE FLOOR MAX REPLACE TRIM
969
+ # CONFIDENCE FORECAST MDETERM REPT TRIMMEAN
970
+ # CORREL FREQUENCY MEDIAN RIGHT TRUE
971
+ # COS FTEST MID ROMAN TRUNC
972
+ # COSH FV MIN ROUND TTEST
973
+ # COUNT GAMMADIST MINUTE ROUNDDOWN TYPE
974
+ # COUNTA GAMMAINV MINVERSE ROUNDUP UPPER
975
+ # COUNTBLANK GAMMALN MIRR ROW VALUE
976
+ # COUNTIF GEOMEAN MMULT ROWS VAR
977
+ # COVAR GROWTH MOD RSQ VARP
978
+ # CRITBINOM HARMEAN MODE SEARCH VDB
979
+ # DATE HLOOKUP MONTH SECOND VLOOKUP
980
+ # DATEVALUE HOUR N SIGN WEEKDAY
981
+ # DAVERAGE HYPGEOMDIST NA SIN WEIBULL
982
+ # DAY IF NEGBINOMDIST SINH YEAR
983
+ # DAYS360 INDEX NORMDIST SKEW ZTEST
984
+ #
985
+ #--
986
+ # You can also modify the module to support function names in the following
987
+ # languages: German, French, Spanish, Portuguese, Dutch, Finnish, Italian and
988
+ # Swedish. See the function_locale.pl program in the examples directory of the distro.
989
+ #++
990
+ #
991
+ # For a general introduction to Excel's formulas and an explanation of the
992
+ # syntax of the function refer to the Excel help files or the following:
993
+ # http://office.microsoft.com/en-us/assistance/CH062528031033.aspx.
994
+ #
995
+ # If your formula doesn't work in WriteExcel try the following:
996
+ #
997
+ # 1. Verify that the formula works in Excel (or Gnumeric or OpenOffice.org).
998
+ # 2. Ensure that it isn't on the Caveats list shown above.
999
+ # 3. Ensure that cell references and formula names are in uppercase.
1000
+ # 4. Ensure that you are using ':' as the range operator, A1:A4.
1001
+ # 5. Ensure that you are using ',' as the union operator, SUM(1,2,3).
1002
+ # 6. Ensure that the function is in the above table.
1003
+ #
1004
+ # If you go through steps 1-6 and you still have a problem, mail me.
1005
+ #
1006
+ # ===Improving performance when working with formulas
1007
+ #
1008
+ # Writing a large number of formulas with WriteExcel can be slow.
1009
+ # This is due to the fact that each formula has to be parsed and with the
1010
+ # current implementation this is computationally expensive.
1011
+ #
1012
+ # However, in a lot of cases the formulas that you write will be quite
1013
+ # similar, for example:
1014
+ #
1015
+ # worksheet.write_formula('B1', '=A1 * 3 + 50', format)
1016
+ # worksheet.write_formula('B2', '=A2 * 3 + 50', format)
1017
+ # ...
1018
+ # ...
1019
+ # worksheet.write_formula('B99', '=A999 * 3 + 50', format)
1020
+ # worksheet.write_formula('B1000', '=A1000 * 3 + 50', format)
1021
+ #
1022
+ # In this example the cell reference changes in iterations from A1 to A1000.
1023
+ # The parser treats this variable as a token and arranges it according to
1024
+ # predefined rules. However, since the parser is oblivious to the value of
1025
+ # the token, it is essentially performing the same calculation 1000 times.
1026
+ # This is inefficient.
1027
+ #
1028
+ # The way to avoid this inefficiency and thereby speed up the writing of
1029
+ # formulas is to parse the formula once and then repeatedly substitute
1030
+ # similar tokens.
1031
+ #
1032
+ # A formula can be parsed and stored via the store_formula() worksheet method.
1033
+ # You can then use the repeat_formula() method to substitute _pattern_,
1034
+ # _replace_ pairs in the stored formula:
1035
+ #
1036
+ # formula = worksheet.store_formula('=A1 * 3 + 50')
1037
+ #
1038
+ # (0...1000).each do |row|
1039
+ # worksheet.repeat_formula(row, 1, formula, format, 'A1', 'A' + (row +1).to_s)
1040
+ # end
1041
+ #
1042
+ # On an arbitrary test machine this method was 10 times faster than the
1043
+ # brute force method shown above.
1044
+ #
1045
+ # It should be noted however that the overall speed of direct formula parsing
1046
+ # will be improved in a future version.
1047
+ #
1048
+ # ==Chart
1049
+ #
1050
+ # ===Synopsis(Chart)
1051
+ #
1052
+ # To create a simple Excel file with a chart using WriteExcel:
1053
+ #
1054
+ # #!/usr/bin/ruby -w
1055
+ #
1056
+ # require 'writeexcel'
1057
+ #
1058
+ # workbook = WriteExcel.new('chart.xls')
1059
+ # worksheet = workbook.add_worksheet
1060
+ #
1061
+ # chart = workbook.add_chart(:type => 'Chart::Column')
1062
+ #
1063
+ # # Configure the chart.
1064
+ # chart.add_series(
1065
+ # :categories => '=Sheet1!$A$2:$A$7',
1066
+ # :values => '=Sheet1!$B$2:$B$7'
1067
+ # )
1068
+ #
1069
+ # # Add the data to the worksheet the chart refers to.
1070
+ # data = [
1071
+ # [ 'Category', 2, 3, 4, 5, 6, 7 ],
1072
+ # [ 'Value', 1, 4, 5, 2, 1, 5 ]
1073
+ # ]
1074
+ #
1075
+ # worksheet.write('A1', data)
1076
+ #
1077
+ # workbook.close
1078
+ #
1079
+ # ===DESCRIPTION(Chart)
1080
+ #
1081
+ # The Chart module is an abstract base class for modules that implement charts
1082
+ # in WriteExcel. The information below is applicable to all of the available
1083
+ # subclasses.
1084
+ #
1085
+ # The Chart module isn't used directly, a chart object is created via the
1086
+ # Workbook add_chart() method where the chart type is specified:
1087
+ #
1088
+ # chart = workbook.add_chart(:type => 'Chart::Column')
1089
+ #
1090
+ # Currently the supported chart types are:
1091
+ #
1092
+ # * 'Chart::Column': Creates a column style (histogram) chart. See Column.
1093
+ # * 'Chart::Bar': Creates a Bar style (transposed histogram) chart. See Bar.
1094
+ # * 'Chart::Line': Creates a Line style chart. See Line.
1095
+ # * 'Chart::Area': Creates an Area (filled line) style chart. See Area.
1096
+ # * 'Chart::Scatter': Creates an Scatter style chart. See Scatter.
1097
+ # * 'Chart::Stock': Creates an Stock style chart. See Stock.
1098
+ #
1099
+ # More chart types will be supported in time. See the "TODO" section.
1100
+ #
1101
+ # === Chart names and links
1102
+ #
1103
+ # The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
1104
+ # support a name property. In general these names can be either a static
1105
+ # string or a link to a worksheet cell. If you choose to use the name_formula
1106
+ # property to specify a link then you should also the name property.
1107
+ # This isn't strictly required by Excel but some third party applications
1108
+ # expect it to be present.
1109
+ #
1110
+ # chartl.set_title(
1111
+ # :name => 'Year End Results',
1112
+ # :name_formula => '=Sheet1!$C$1'
1113
+ # )
1114
+ #
1115
+ # These links should be used sparingly since they aren't commonly
1116
+ # used in Excel charts.
1117
+ #
1118
+ # === Chart names and Unicode
1119
+ #
1120
+ # The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
1121
+ # support a name property. These names can be UTF8 strings.
1122
+ #
1123
+ # This methodology is explained in the "UNICODE IN EXCEL" section of WriteExcel
1124
+ # but is semi-deprecated. If you are using Unicode the easiest option is to
1125
+ # just use UTF8.
1126
+ #
1127
+ # === TODO(Chart)
1128
+ #
1129
+ # Charts in WriteExcel are a work in progress. More chart types and
1130
+ # features will be added in time. Please be patient. Even a small feature
1131
+ # can take a week or more to implement, test and document.
1132
+ #
1133
+ # Features that are on the TODO list and will be added are:
1134
+ #
1135
+ # * Additional chart types. Stock, Pie and Scatter charts are next in line.
1136
+ # Send an email if you are interested in other types and they will be
1137
+ # added to the queue.
1138
+ # * Colours and formatting options. For now you will have to make do
1139
+ # with the default Excel colours and formats.
1140
+ # * Axis controls, gridlines.
1141
+ # * Embedded data in charts for third party application support.
1142
+ #
1143
+ # == KNOWN ISSUES(Chart)
1144
+ #
1145
+ # * Currently charts don't contain embedded data from which the charts
1146
+ # can be rendered. Excel and most other third party applications ignore
1147
+ # this and read the data via the links that have been specified. However,
1148
+ # some applications may complain or not render charts correctly. The
1149
+ # preview option in Mac OS X is an known example. This will be fixed
1150
+ # in a later release.
1151
+ # * When there are several charts with titles set in a workbook some of
1152
+ # the titles may display at a font size of 10 instead of the default
1153
+ # 12 until another chart with the title set is viewed.
1154
+ #
1155
+ class WriteExcel < Workbook
1156
+ if RUBY_VERSION < '1.9'
1157
+ $KCODE = 'u'
1158
+ end
1159
+ end