ruby_pptx 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +98 -0
  3. data/README.md +94 -4
  4. data/lib/ruby_pptx/action.rb +12 -4
  5. data/lib/ruby_pptx/autoshape_spec.rb +6 -2
  6. data/lib/ruby_pptx/builder.rb +3 -1
  7. data/lib/ruby_pptx/chart/categories.rb +45 -15
  8. data/lib/ruby_pptx/chart/chart.rb +168 -31
  9. data/lib/ruby_pptx/chart/combo.rb +19 -4
  10. data/lib/ruby_pptx/chart/data.rb +45 -15
  11. data/lib/ruby_pptx/chart/format.rb +229 -76
  12. data/lib/ruby_pptx/chart/workbook_writer.rb +9 -3
  13. data/lib/ruby_pptx/chart/xml_writer.rb +54 -18
  14. data/lib/ruby_pptx/chart/xy_data.rb +68 -22
  15. data/lib/ruby_pptx/dml/color.rb +27 -9
  16. data/lib/ruby_pptx/dml/effect.rb +6 -2
  17. data/lib/ruby_pptx/dml/fill.rb +42 -14
  18. data/lib/ruby_pptx/element_proxy.rb +12 -4
  19. data/lib/ruby_pptx/enum/base.rb +30 -10
  20. data/lib/ruby_pptx/enum/prog_id.rb +3 -1
  21. data/lib/ruby_pptx/geometry.rb +32 -10
  22. data/lib/ruby_pptx/image.rb +27 -9
  23. data/lib/ruby_pptx/length.rb +94 -27
  24. data/lib/ruby_pptx/media.rb +12 -4
  25. data/lib/ruby_pptx/numeric_lengths.rb +34 -9
  26. data/lib/ruby_pptx/opc/oxml.rb +7 -5
  27. data/lib/ruby_pptx/opc/pack_uri.rb +15 -5
  28. data/lib/ruby_pptx/opc/package.rb +97 -31
  29. data/lib/ruby_pptx/opc/serialized.rb +15 -5
  30. data/lib/ruby_pptx/oxml/backend.rb +585 -0
  31. data/lib/ruby_pptx/oxml/chart.rb +112 -42
  32. data/lib/ruby_pptx/oxml/content_model.rb +6 -2
  33. data/lib/ruby_pptx/oxml/dml/color.rb +6 -2
  34. data/lib/ruby_pptx/oxml/dml/fill.rb +6 -2
  35. data/lib/ruby_pptx/oxml/element.rb +138 -101
  36. data/lib/ruby_pptx/oxml/ns.rb +7 -7
  37. data/lib/ruby_pptx/oxml/presentation.rb +9 -3
  38. data/lib/ruby_pptx/oxml/section.rb +3 -1
  39. data/lib/ruby_pptx/oxml/shapes/autoshape.rb +39 -13
  40. data/lib/ruby_pptx/oxml/shapes/groupshape.rb +15 -7
  41. data/lib/ruby_pptx/oxml/shapes/other.rb +47 -16
  42. data/lib/ruby_pptx/oxml/shapes/shared.rb +96 -30
  43. data/lib/ruby_pptx/oxml/simple_types.rb +169 -52
  44. data/lib/ruby_pptx/oxml/slide.rb +25 -8
  45. data/lib/ruby_pptx/oxml/table.rb +39 -13
  46. data/lib/ruby_pptx/oxml/text.rb +122 -16
  47. data/lib/ruby_pptx/oxml/theme.rb +13 -4
  48. data/lib/ruby_pptx/package.rb +9 -3
  49. data/lib/ruby_pptx/parts/chart.rb +6 -2
  50. data/lib/ruby_pptx/parts/image.rb +12 -4
  51. data/lib/ruby_pptx/parts/media.rb +3 -1
  52. data/lib/ruby_pptx/parts/presentation.rb +15 -5
  53. data/lib/ruby_pptx/parts/slide.rb +33 -11
  54. data/lib/ruby_pptx/parts/theme.rb +3 -1
  55. data/lib/ruby_pptx/pattern_matching.rb +6 -2
  56. data/lib/ruby_pptx/presentation.rb +24 -8
  57. data/lib/ruby_pptx/section.rb +30 -10
  58. data/lib/ruby_pptx/shapes/adjustments.rb +9 -3
  59. data/lib/ruby_pptx/shapes/authoring.rb +3 -1
  60. data/lib/ruby_pptx/shapes/base.rb +74 -24
  61. data/lib/ruby_pptx/shapes/freeform.rb +36 -12
  62. data/lib/ruby_pptx/shapes/placeholder.rb +44 -15
  63. data/lib/ruby_pptx/shapes/shape.rb +91 -30
  64. data/lib/ruby_pptx/shapes/shape_tree.rb +235 -121
  65. data/lib/ruby_pptx/slide.rb +137 -46
  66. data/lib/ruby_pptx/table.rb +105 -35
  67. data/lib/ruby_pptx/text/font_metrics.rb +30 -9
  68. data/lib/ruby_pptx/text/list_style.rb +88 -0
  69. data/lib/ruby_pptx/text/text.rb +241 -59
  70. data/lib/ruby_pptx/theme.rb +30 -10
  71. data/lib/ruby_pptx/version.rb +1 -1
  72. data/lib/ruby_pptx.rb +9 -1
  73. metadata +24 -2
@@ -87,7 +87,9 @@ module Pptx
87
87
  end
88
88
 
89
89
  # A group counts as one shape, whatever it contains.
90
- def size = member_elements.size
90
+ def size
91
+ member_elements.size
92
+ end
91
93
  alias length size
92
94
 
93
95
  def [](index, length = nil)
@@ -158,15 +160,23 @@ module Pptx
158
160
 
159
161
  # Which shape elements belong to this collection; placeholder collections
160
162
  # narrow this.
161
- def member?(_shape_element) = true
163
+ def member?(_shape_element)
164
+ true
165
+ end
162
166
 
163
- def member_elements = @sp_tree.shape_elements.select { |e| member?(e) }
167
+ def member_elements
168
+ @sp_tree.shape_elements.select { |e| member?(e) }
169
+ end
164
170
 
165
- def shape_factory(shape_element) = ShapeFactory.build(shape_element, self)
171
+ def shape_factory(shape_element)
172
+ ShapeFactory.build(shape_element, self)
173
+ end
166
174
 
167
175
  # One more than the highest id in use. Note the shape tree's own allocator
168
176
  # fills gaps instead; both behaviours are inherited from python-pptx.
169
- def next_shape_id = @sp_tree.max_shape_id + 1
177
+ def next_shape_id
178
+ @sp_tree.max_shape_id + 1
179
+ end
170
180
 
171
181
  # Office's icon for an Office document, a generic one for anything else.
172
182
  def default_ole_icon(prog_id)
@@ -188,12 +198,12 @@ module Pptx
188
198
  end
189
199
  end
190
200
 
191
- # A shape collection you can add shapes to: a slide's tree, or a group
192
- # within one.
201
+ # Adding the shapes a slide, layout or master can all hold: auto shapes,
202
+ # pictures, text boxes, connectors, freeforms and groups. Charts, tables,
203
+ # movies and OLE objects need a slide and stay in {BaseGroupShapes}.
193
204
  #
194
- # Adding to a group changes the group's extents, so every method here ends
195
- # by recalculating them. On a slide that is a no-op.
196
- class BaseGroupShapes < BaseShapes
205
+ # Expects +@sp_tree+, +part+ and +shape_factory+ from the including class.
206
+ module ShapeAuthoring
197
207
  # Add an auto shape.
198
208
  #
199
209
  # shapes.add_shape(:rounded_rectangle,
@@ -213,7 +223,7 @@ module Pptx
213
223
  sp = @sp_tree.add_autoshape(id, name, Enum::MSO_SHAPE.to_xml(member),
214
224
  left, top, width, height)
215
225
  recalculate_extents
216
- shape_factory(sp)
226
+ drawn(sp)
217
227
  end
218
228
 
219
229
  # Add a picture showing the image in +image_file+, which may be a path or
@@ -249,9 +259,127 @@ module Pptx
249
259
  end
250
260
 
251
261
  recalculate_extents
252
- shape_factory(pic)
262
+ drawn(pic)
263
+ end
264
+
265
+ # Add an empty text box.
266
+ #
267
+ # @return [Shape]
268
+ def add_textbox(at:, size:)
269
+ left, top = at
270
+ width, height = size
271
+ id = next_shape_id
272
+ sp = @sp_tree.add_textbox(id, "TextBox #{id - 1}", left, top, width, height)
273
+ recalculate_extents
274
+ drawn(sp)
275
+ end
276
+
277
+ # Add a connector between two points.
278
+ #
279
+ # A connector is stored as a bounding box with flip flags rather than as
280
+ # two points, so the end points are converted here.
281
+ #
282
+ # @return [Connector]
283
+ def add_connector(connector_type, begin_at:, end_at:)
284
+ member = Enum::MSO_CONNECTOR_TYPE.fetch(connector_type)
285
+ begin_x, begin_y = begin_at.map { |value| Length.coerce(value).emu }
286
+ end_x, end_y = end_at.map { |value| Length.coerce(value).emu }
287
+
288
+ id = next_shape_id
289
+ cxn_sp = @sp_tree.add_cxnSp(
290
+ id, "Connector #{id - 1}", Enum::MSO_CONNECTOR_TYPE.to_xml(member),
291
+ [begin_x, end_x].min, [begin_y, end_y].min,
292
+ (end_x - begin_x).abs, (end_y - begin_y).abs,
293
+ begin_x > end_x, begin_y > end_y
294
+ )
295
+ recalculate_extents
296
+ drawn(cxn_sp)
297
+ end
298
+
299
+ # Start building a freeform shape.
300
+ #
301
+ # +scale+ says how many EMU one local coordinate unit is worth, so a shape
302
+ # can be described in convenient numbers; pass a pair for different
303
+ # horizontal and vertical scales.
304
+ #
305
+ # @return [FreeformBuilder]
306
+ def build_freeform(start_x: 0, start_y: 0, scale: 1.0)
307
+ FreeformBuilder.new_builder(self, start_x, start_y, scale)
308
+ end
309
+
310
+ # Build a freeform shape and add it, in one call.
311
+ #
312
+ # shapes.add_freeform(at: [x, y], scale: Pptx.inches(1).emu / 100.0) do |f|
313
+ # f.line_to(100, 0)
314
+ # f.line_to(50, 100)
315
+ # end
316
+ #
317
+ # @return [Shape]
318
+ def add_freeform(at: [0, 0], start_x: 0, start_y: 0, scale: 1.0, close: true)
319
+ builder = build_freeform(start_x: start_x, start_y: start_y, scale: scale)
320
+ yield builder if block_given?
321
+ builder.close if close
322
+ builder.convert_to_shape(origin_at: at)
253
323
  end
254
324
 
325
+ # @api private
326
+ # Used by FreeformBuilder, which needs to add the element and then draw
327
+ # into it.
328
+ def add_freeform_element(x, y, width, height)
329
+ @sp_tree.add_freeform_sp(x, y, width, height)
330
+ end
331
+
332
+ # @api private
333
+ def build_shape(shape_element)
334
+ recalculate_extents
335
+ drawn(shape_element)
336
+ end
337
+
338
+ # Add a group, optionally moving +shapes+ into it.
339
+ #
340
+ # The group has no position or size of its own: both follow from what it
341
+ # contains, and are recomputed whenever its contents change.
342
+ #
343
+ # @return [GroupShape]
344
+ def add_group_shape(shapes = [])
345
+ grp_sp = @sp_tree.add_grpSp
346
+ shapes.each { |shape| grp_sp.insert_element_before(shape.element, "p:extLst") }
347
+ grp_sp.recalculate_extents unless shapes.empty?
348
+ recalculate_extents
349
+ drawn(grp_sp)
350
+ end
351
+
352
+ private
353
+
354
+ # The proxy for a shape just added. PowerPoint marks shapes drawn on a
355
+ # layout or master `userDrawn`, so an including class can ask for that.
356
+ def drawn(element)
357
+ if user_drawn?
358
+ nv_pr = element.element_children.first&.find("p:nvPr")
359
+ nv_pr&.set("userDrawn", "1")
360
+ end
361
+ shape_factory(element)
362
+ end
363
+
364
+ def user_drawn?
365
+ false
366
+ end
367
+
368
+ # A group resizes itself around its contents; a slide, layout or master
369
+ # does not move.
370
+ def recalculate_extents
371
+ nil
372
+ end
373
+ end
374
+
375
+ # A shape collection you can add shapes to: a slide's tree, or a group
376
+ # within one.
377
+ #
378
+ # Adding to a group changes the group's extents, so every method here ends
379
+ # by recalculating them. On a slide that is a no-op.
380
+ class BaseGroupShapes < BaseShapes
381
+ include ShapeAuthoring
382
+
255
383
  # Add a movie showing the video in +movie_file+.
256
384
  #
257
385
  # The size must be given: unlike a picture, a video is not interrogated
@@ -372,66 +500,6 @@ module Pptx
372
500
  shape_factory(frame)
373
501
  end
374
502
 
375
- # Add an empty text box.
376
- #
377
- # @return [Shape]
378
- def add_textbox(at:, size:)
379
- left, top = at
380
- width, height = size
381
- id = next_shape_id
382
- sp = @sp_tree.add_textbox(id, "TextBox #{id - 1}", left, top, width, height)
383
- recalculate_extents
384
- shape_factory(sp)
385
- end
386
-
387
- # Add a connector between two points.
388
- #
389
- # A connector is stored as a bounding box with flip flags rather than as
390
- # two points, so the end points are converted here.
391
- #
392
- # @return [Connector]
393
- def add_connector(connector_type, begin_at:, end_at:)
394
- member = Enum::MSO_CONNECTOR_TYPE.fetch(connector_type)
395
- begin_x, begin_y = begin_at.map { |value| Length.coerce(value).emu }
396
- end_x, end_y = end_at.map { |value| Length.coerce(value).emu }
397
-
398
- id = next_shape_id
399
- cxn_sp = @sp_tree.add_cxnSp(
400
- id, "Connector #{id - 1}", Enum::MSO_CONNECTOR_TYPE.to_xml(member),
401
- [begin_x, end_x].min, [begin_y, end_y].min,
402
- (end_x - begin_x).abs, (end_y - begin_y).abs,
403
- begin_x > end_x, begin_y > end_y
404
- )
405
- recalculate_extents
406
- shape_factory(cxn_sp)
407
- end
408
-
409
- # Start building a freeform shape.
410
- #
411
- # +scale+ says how many EMU one local coordinate unit is worth, so a shape
412
- # can be described in convenient numbers; pass a pair for different
413
- # horizontal and vertical scales.
414
- #
415
- # @return [FreeformBuilder]
416
- def build_freeform(start_x: 0, start_y: 0, scale: 1.0)
417
- FreeformBuilder.new_builder(self, start_x, start_y, scale)
418
- end
419
-
420
- # Build a freeform shape and add it, in one call.
421
- #
422
- # shapes.add_freeform(at: [x, y], scale: Pptx.inches(1).emu / 100.0) do |f|
423
- # f.line_to(100, 0)
424
- # f.line_to(50, 100)
425
- # end
426
- #
427
- # @return [Shape]
428
- def add_freeform(at: [0, 0], start_x: 0, start_y: 0, scale: 1.0, close: true)
429
- builder = build_freeform(start_x: start_x, start_y: start_y, scale: scale)
430
- yield builder if block_given?
431
- builder.close if close
432
- builder.convert_to_shape(origin_at: at)
433
- end
434
-
435
503
  # The loudspeaker still PowerPoint shows for a video with no poster frame.
436
504
  def default_poster_frame
437
505
  StringIO.new(File.binread(
@@ -447,50 +515,35 @@ module Pptx
447
515
  slide_element.get_or_add_child_time_node_list.add_video(pic.shape_id)
448
516
  end
449
517
 
450
- # @api private
451
- # Used by FreeformBuilder, which needs to add the element and then draw
452
- # into it.
453
- def add_freeform_element(x, y, width, height)
454
- @sp_tree.add_freeform_sp(x, y, width, height)
455
- end
456
-
457
- # @api private
458
- def build_shape(shape_element)
459
- recalculate_extents
460
- shape_factory(shape_element)
461
- end
462
-
463
- # Add a group, optionally moving +shapes+ into it.
464
- #
465
- # The group has no position or size of its own: both follow from what it
466
- # contains, and are recomputed whenever its contents change.
467
- #
468
- # @return [GroupShape]
469
- def add_group_shape(shapes = [])
470
- grp_sp = @sp_tree.add_grpSp
471
- shapes.each { |shape| grp_sp.insert_element_before(shape.element, "p:extLst") }
472
- grp_sp.recalculate_extents unless shapes.empty?
473
- recalculate_extents
474
- shape_factory(grp_sp)
475
- end
476
-
477
518
  private
478
519
 
479
520
  # A group resizes itself around its contents; a slide does not move.
480
- def recalculate_extents = nil
521
+ def recalculate_extents
522
+ nil
523
+ end
481
524
 
482
- def shape_factory(shape_element) = ShapeFactory.build_for_slide(shape_element, self)
525
+ def shape_factory(shape_element)
526
+ ShapeFactory.build_for_slide(shape_element, self)
527
+ end
483
528
  end
484
529
 
485
530
  # The shapes on a slide.
486
531
  class SlideShapes < BaseGroupShapes
487
532
  # Copy the layout's placeholders onto this slide, preserving z-order.
488
533
  #
489
- # Latent placeholders -- date, footer and slide number -- are not cloned:
490
- # PowerPoint shows them from the layout without materialising them on the
491
- # slide.
492
- def clone_layout_placeholders(slide_layout)
493
- slide_layout.cloneable_placeholders.each { |ph| clone_placeholder(ph) }
534
+ # Date, footer and slide number are left out unless +footers+ is true:
535
+ # PowerPoint draws them only where the slide carries the placeholder
536
+ # itself, which is what switching them on in its Header & Footer dialog
537
+ # does. With +footers+, their text -- the slide-number field, say -- is
538
+ # copied from the layout too, since an empty one shows nothing.
539
+ def clone_layout_placeholders(slide_layout, footers: false)
540
+ chosen = footers ? slide_layout.placeholders.to_a : slide_layout.cloneable_placeholders
541
+ chosen.each do |ph|
542
+ sp = clone_placeholder(ph)
543
+ if footers && SlideLayout::LATENT_PLACEHOLDER_TYPES.include?(ph.element.ph_type)
544
+ copy_text_body(ph.element, sp)
545
+ end
546
+ end
494
547
  self
495
548
  end
496
549
 
@@ -502,11 +555,26 @@ module Pptx
502
555
  element && shape_factory(element)
503
556
  end
504
557
 
505
- def placeholders = parent.placeholders
558
+ def placeholders
559
+ parent.placeholders
560
+ end
506
561
 
507
562
  private
508
563
 
509
- def shape_factory(shape_element) = ShapeFactory.build_for_slide(shape_element, self)
564
+ def shape_factory(shape_element)
565
+ ShapeFactory.build_for_slide(shape_element, self)
566
+ end
567
+
568
+ # Replace +target+'s text body with a copy of +source+'s.
569
+ def copy_text_body(source, target)
570
+ body = source.find("p:txBody")
571
+ return if body.nil?
572
+
573
+ copy = target.build_from_xml(body.to_xml)
574
+ old = target.find("p:txBody")
575
+ target.remove(old) if old
576
+ target.insert_element_before(copy, "p:extLst")
577
+ end
510
578
  end
511
579
 
512
580
  # The shapes inside a `p:grpSp`.
@@ -522,16 +590,32 @@ module Pptx
522
590
 
523
591
  # The shapes on a slide layout.
524
592
  class LayoutShapes < BaseShapes
593
+ include ShapeAuthoring
594
+
525
595
  private
526
596
 
527
- def shape_factory(shape_element) = ShapeFactory.build_for_layout(shape_element, self)
597
+ def user_drawn?
598
+ true
599
+ end
600
+
601
+ def shape_factory(shape_element)
602
+ ShapeFactory.build_for_layout(shape_element, self)
603
+ end
528
604
  end
529
605
 
530
606
  # The shapes on a slide master.
531
607
  class MasterShapes < BaseShapes
608
+ include ShapeAuthoring
609
+
532
610
  private
533
611
 
534
- def shape_factory(shape_element) = ShapeFactory.build_for_master(shape_element, self)
612
+ def user_drawn?
613
+ true
614
+ end
615
+
616
+ def shape_factory(shape_element)
617
+ ShapeFactory.build_for_master(shape_element, self)
618
+ end
535
619
  end
536
620
 
537
621
  # The shapes on a notes page.
@@ -554,45 +638,71 @@ module Pptx
554
638
 
555
639
  private
556
640
 
557
- def shape_factory(shape_element) = ShapeFactory.build_for_notes_slide(shape_element, self)
641
+ def shape_factory(shape_element)
642
+ ShapeFactory.build_for_notes_slide(shape_element, self)
643
+ end
558
644
  end
559
645
 
560
646
  # The placeholders on a notes page.
561
647
  class NotesSlidePlaceholders < NotesSlideShapes
562
648
  # @return [NotesSlidePlaceholder, nil]
563
- def by_type(ph_type) = find { |ph| ph.element.ph_type == ph_type }
649
+ def by_type(ph_type)
650
+ find { |ph| ph.element.ph_type == ph_type }
651
+ end
564
652
 
565
653
  private
566
654
 
567
- def member?(shape_element) = shape_element.placeholder?
655
+ def member?(shape_element)
656
+ shape_element.placeholder?
657
+ end
568
658
  end
569
659
 
570
660
  # The placeholders of a slide layout, in `idx` order.
571
661
  class LayoutPlaceholders < LayoutShapes
572
662
  include PlaceholderAuthoring
573
663
 
664
+ # A placeholder view only lists placeholders, so a shape added through it
665
+ # would vanish from the collection it was added to.
666
+ private(*ShapeAuthoring.public_instance_methods)
667
+
574
668
  # @return [LayoutPlaceholder, nil]
575
- def by_idx(idx) = find { |ph| ph.element.ph_idx == idx }
669
+ def by_idx(idx)
670
+ find { |ph| ph.element.ph_idx == idx }
671
+ end
576
672
 
577
673
  private
578
674
 
579
- def member?(shape_element) = shape_element.placeholder?
675
+ def member?(shape_element)
676
+ shape_element.placeholder?
677
+ end
580
678
 
581
- def member_elements = super.sort_by(&:ph_idx)
679
+ def member_elements
680
+ super.sort_by(&:ph_idx)
681
+ end
582
682
  end
583
683
 
584
684
  # The placeholders of a slide master, in `idx` order.
585
685
  class MasterPlaceholders < MasterShapes
586
686
  include PlaceholderAuthoring
587
687
 
688
+ # A placeholder view only lists placeholders, so a shape added through it
689
+ # would vanish from the collection it was added to.
690
+ private(*ShapeAuthoring.public_instance_methods)
691
+
588
692
  # @return [MasterPlaceholder, nil]
589
- def by_type(ph_type) = find { |ph| ph.element.ph_type == ph_type }
693
+ def by_type(ph_type)
694
+ find { |ph| ph.element.ph_type == ph_type }
695
+ end
590
696
 
591
697
  private
592
698
 
593
- def member?(shape_element) = shape_element.placeholder?
699
+ def member?(shape_element)
700
+ shape_element.placeholder?
701
+ end
594
702
 
595
- def member_elements = super.sort_by(&:ph_idx)
703
+ def member_elements
704
+ super.sort_by(&:ph_idx)
705
+ end
596
706
  end
597
707
 
598
708
  # The placeholders of a slide.
@@ -614,7 +724,9 @@ module Pptx
614
724
  self
615
725
  end
616
726
 
617
- def size = @sp_tree.placeholder_elements.count
727
+ def size
728
+ @sp_tree.placeholder_elements.count
729
+ end
618
730
  alias length size
619
731
 
620
732
  # The placeholder whose `idx` is +idx+, or nil.
@@ -629,6 +741,8 @@ module Pptx
629
741
 
630
742
  private
631
743
 
632
- def placeholder_elements = @sp_tree.placeholder_elements.sort_by(&:ph_idx)
744
+ def placeholder_elements
745
+ @sp_tree.placeholder_elements.sort_by(&:ph_idx)
746
+ end
633
747
  end
634
748
  end