ruby_pptx 0.1.0

data/lib/ruby_pptx/section.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/pattern_matching"
+
+require "ruby_pptx/sliceable"
+
+require "ruby_pptx/element_proxy"
+
+module Pptx
+  # The sections of a presentation.
+  #
+  # Sections group slides in the thumbnail pane and in presenter view. They are
+  # a PowerPoint 2010 extension rather than part of the base PresentationML
+  # schema, and python-pptx does not model them at all.
+  #
+  #   prs.sections.add("Introduction", slides: prs.slides.first(2))
+  #   prs.sections["Introduction"].slides.map(&:slide_id)
+  class Sections
+    include DeconstructToArray
+
+    include Sliceable
+    include Enumerable
+
+    def initialize(presentation)
+      @presentation = presentation
+    end
+
+    def each
+      return enum_for(:each) { size } unless block_given?
+
+      section_elements.each { |element| yield Section.new(element, @presentation) }
+      self
+    end
+
+    def size = section_elements.size
+    alias length size
+
+    def empty? = size.zero?
+
+    # Indexed by position, or looked up by name.
+    def [](key, length = nil)
+      return by_name(key) if key.is_a?(String)
+
+      slice_members(section_elements, key, length) { |element| Section.new(element, @presentation) }
+    end
+
+    # @return [Section, nil]
+    def by_name(name) = find { |section| section.name == name }
+
+    # Add a section, optionally containing +slides+.
+    #
+    # @return [Section]
+    def add(name, slides: [])
+      element = @presentation.element.get_or_add_section_list.add_section(name)
+      Section.new(element, @presentation).tap do |section|
+        slides.each { |slide| section << slide }
+      end
+    end
+
+    # Remove a section. Its slides stay in the presentation; only the grouping
+    # goes away, which is what PowerPoint does when a section is removed
+    # without its slides.
+    def delete(section)
+      list = @presentation.element.section_list
+      return nil if list.nil?
+
+      list.remove(section.element)
+      @presentation.element.remove_section_list if list.section_list.empty?
+      section
+    end
+
+    def inspect = "#<Pptx::Sections #{map(&:name).inspect}>"
+
+    private
+
+    def section_elements = @presentation.element.section_list&.section_list || []
+  end
+
+  # One named section of a presentation.
+  class Section < ElementProxy
+    include PatternMatching
+
+    pattern_keys :name, :id, :slides
+
+    def initialize(element, presentation)
+      super(element)
+      @presentation = presentation
+    end
+
+    def name = @element.name
+
+    def name=(value)
+      @element.name = value.to_s
+    end
+
+    # The GUID PowerPoint uses to identify this section.
+    def id = @element.id
+
+    # The slides in this section, in section order.
+    #
+    # A section stores slide ids, so a slide deleted from the presentation
+    # simply drops out here rather than leaving a dangling entry.
+    def slides
+      slide_ids.filter_map { |slide_id| @presentation.slides.by_id(slide_id) }
+    end
+
+    def slide_ids = @element.sldIdLst.sldId_list.map(&:id)
+
+    # Put +slide+ in this section. A slide belongs to at most one section, so
+    # it is removed from any other first.
+    def <<(slide)
+      @presentation.sections.each { |other| other.delete_slide(slide) unless other == self }
+      return self if slide_ids.include?(slide.slide_id)
+
+      @element.sldIdLst.add_sldId(id: slide.slide_id)
+      self
+    end
+    alias add_slide <<
+
+    def delete_slide(slide)
+      entry = @element.sldIdLst.sldId_list.find { |e| e.id == slide.slide_id }
+      @element.sldIdLst.remove(entry) if entry
+      slide
+    end
+
+    def include?(slide) = slide_ids.include?(slide.slide_id)
+
+    def inspect = "#<Pptx::Section #{name.inspect} slides=#{slide_ids.size}>"
+  end
+end

data/lib/ruby_pptx/shapes/adjustments.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/autoshape_spec"
+
+module Pptx
+  # The adjustment handles of an auto shape -- the yellow diamonds that set
+  # how round a rounded rectangle is, or how deep a chevron's notch goes.
+  #
+  #   shape.adjustments[0]          #=> 0.16667
+  #   shape.adjustments[0] = 0.4
+  #
+  # Values are fractions: 0.5 is half way. Many shapes allow values below
+  # 0.0 or above 1.0 at extreme proportions, so neither bound is enforced.
+  #
+  # Every handle the shape type defines is always present, at its default
+  # until set. Setting any one writes all of them, as PowerPoint does.
+  class Adjustments
+    include Enumerable
+
+    # The file stores adjustments on a scale of 100,000.
+    SCALE = 100_000.0
+
+    Adjustment = Struct.new(:name, :default, :actual) do
+      def raw = actual || default
+    end
+
+    # @param preset_geometry [Pptx::Oxml::Element, nil] the shape's
+    #   `a:prstGeom`; nil for a freeform, which has no handles
+    def initialize(preset_geometry)
+      @geometry = preset_geometry
+      @adjustments = initial_adjustments
+    end
+
+    # @return [Float, nil] nil past the last handle, as Array does
+    def [](index)
+      adjustment = @adjustments[index]
+      adjustment && (adjustment.raw / SCALE)
+    end
+
+    def []=(index, value)
+      unless value.is_a?(Numeric)
+        raise ArgumentError,
+              "adjustment values must be numeric, got #{value.inspect}"
+      end
+
+      adjustment = @adjustments[index] or
+        raise IndexError, "this shape has #{size} adjustment#{"s" unless size == 1}, not #{index + 1}"
+      # Truncated, not rounded, to match python-pptx: 0.29 is stored as 28999.
+      adjustment.actual = (value * SCALE).to_i
+      @geometry.rewrite_guides(@adjustments.map { |a| [a.name, a.raw] })
+    end
+
+    def each
+      return enum_for(:each) { size } unless block_given?
+
+      @adjustments.each { |a| yield a.raw / SCALE }
+      self
+    end
+
+    def size = @adjustments.size
+    alias length size
+
+    def inspect = "#<Pptx::Adjustments #{to_a.inspect}>"
+
+    private
+
+    # The type's defaults, overlaid with any values the file records. A
+    # guide naming no handle of this type is ignored rather than trusted.
+    def initial_adjustments
+      return [] if @geometry.nil?
+
+      adjustments = AutoShapeSpec.default_adjustments(@geometry.prst.name).map do |name, default|
+        Adjustment.new(name, default)
+      end
+      by_name = adjustments.to_h { |a| [a.name, a] }
+      @geometry.gd_list.each do |gd|
+        target = by_name[gd.name] or next
+        target.actual = Integer(gd.fmla.delete_prefix("val "), 10)
+      end
+      adjustments
+    end
+  end
+end

data/lib/ruby_pptx/shapes/authoring.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Pptx
+  # Adding placeholders to a slide master or a slide layout.
+  #
+  # A slide's placeholders are cloned from its layout and are not created
+  # directly, so this is mixed into the master and layout collections only.
+  module PlaceholderAuthoring
+    # Add a placeholder.
+    #
+    #   master.placeholders.add(:title, at: [x, y], size: [cx, cy])
+    #   layout.placeholders.add(:body, idx: 1, at: [x, y], size: [cx, cy])
+    #
+    # A title placeholder carries no `idx` -- there is only ever one, and
+    # PowerPoint identifies it by type. Every other kind needs one, and gets
+    # the next free value unless told otherwise. The `idx` is what ties a
+    # layout placeholder to the master placeholder it inherits from, so it is
+    # worth setting deliberately when the two should line up.
+    #
+    # @param ph_type [Symbol, Pptx::Enum::PP_PLACEHOLDER_TYPE]
+    # @param at [Array(Length, Length), nil] position; inherited when omitted
+    # @param size [Array(Length, Length), nil] size; inherited when omitted
+    # @param idx [Integer, nil]
+    # @param orient [Symbol, nil] :vertical for a vertical placeholder
+    # @param sz [Symbol, nil] :full, :half or :quarter, the size hint
+    #   PowerPoint uses when it rebuilds a layout
+    # @return [Shape] the new placeholder
+    def add(ph_type, at: nil, size: nil, idx: nil, orient: nil, sz: nil)
+      type = Enum::PP_PLACEHOLDER_TYPE.fetch(ph_type)
+      idx = resolve_idx(type, idx)
+      id = next_shape_id
+      element = @sp_tree.add_placeholder(id, next_placeholder_name(type, id, orient),
+                                         type, orient_value(orient), sz_value(sz), idx)
+      shape = shape_factory(element)
+      place(shape, at, size)
+      shape
+    end
+
+    # Add the five placeholders PowerPoint expects a master to have.
+    #
+    # Their geometry is the Office default scaled to +slide_size+, so a master
+    # added to a 4:3 deck reproduces the familiar layout exactly and a 16:9
+    # deck gets the same proportions rather than a 4:3 block in the corner.
+    def add_standard_set(slide_size)
+      width, height = slide_size
+      STANDARD_PLACEHOLDERS.each do |ph_type, idx, sz, (x, y, cx, cy)|
+        add(ph_type, idx: idx, sz: sz,
+                     at: [scale(x, width), scale(y, height)],
+                     size: [scale(cx, width), scale(cy, height)])
+      end
+      self
+    end
+
+    # Fractions of the slide, taken from the Office default master, whose
+    # slide is 9144000 x 6858000 EMU.
+    STANDARD_PLACEHOLDERS = [
+      [:TITLE, nil, nil, [457_200 / 9_144_000.0, 274_638 / 6_858_000.0,
+                          8_229_600 / 9_144_000.0, 1_143_000 / 6_858_000.0]],
+      [:BODY, 1, nil, [457_200 / 9_144_000.0, 1_600_200 / 6_858_000.0,
+                       8_229_600 / 9_144_000.0, 4_525_963 / 6_858_000.0]],
+      [:DATE, 2, :half, [457_200 / 9_144_000.0, 6_356_350 / 6_858_000.0,
+                         2_133_600 / 9_144_000.0, 365_125 / 6_858_000.0]],
+      [:FOOTER, 3, :quarter, [3_124_200 / 9_144_000.0, 6_356_350 / 6_858_000.0,
+                              2_895_600 / 9_144_000.0, 365_125 / 6_858_000.0]],
+      [:SLIDE_NUMBER, 4, :quarter, [6_553_200 / 9_144_000.0, 6_356_350 / 6_858_000.0,
+                                    2_133_600 / 9_144_000.0, 365_125 / 6_858_000.0]]
+    ].freeze
+
+    SIZES = {
+      full: Oxml::SimpleTypes::ST_PlaceholderSize::FULL,
+      half: Oxml::SimpleTypes::ST_PlaceholderSize::HALF,
+      quarter: Oxml::SimpleTypes::ST_PlaceholderSize::QUARTER
+    }.freeze
+
+    private
+
+    def scale(fraction, extent) = Length.emu((fraction * extent.emu).round)
+
+    def place(shape, at, size)
+      shape.left, shape.top = at if at
+      shape.width, shape.height = size if size
+    end
+
+    # A title is identified by type; everything else by idx, which must be
+    # unique within the shape tree.
+    def resolve_idx(type, idx)
+      return nil if %i[TITLE CENTER_TITLE].include?(type.name)
+      return idx unless idx.nil?
+
+      used = member_elements.filter_map(&:ph_idx)
+      (1..).find { |candidate| !used.include?(candidate) }
+    end
+
+    def orient_value(orient)
+      return nil if orient.nil?
+
+      raise ArgumentError, "orient must be :vertical or nil, got #{orient.inspect}" unless orient == :vertical
+
+      Oxml::SimpleTypes::ST_Direction::VERT
+    end
+
+    def sz_value(sz)
+      return nil if sz.nil?
+
+      SIZES.fetch(sz) do
+        raise ArgumentError, "sz must be :full, :half or :quarter, got #{sz.inspect}"
+      end
+    end
+  end
+end

data/lib/ruby_pptx/shapes/base.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/pattern_matching"
+
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/enum/shapes"
+require "ruby_pptx/action"
+
+module Pptx
+  # A shape on a slide, layout or master.
+  #
+  # Subclasses cover the specific kinds: {Shape} for auto shapes and text
+  # boxes, {Picture}, {GraphicFrame}, {Connector} and {GroupShape}.
+  class BaseShape
+    include PatternMatching
+
+    pattern_keys :shape_id, :name, :shape_type, :left, :top, :width, :height,
+                 :rotation, :placeholder_format
+
+    attr_reader :element, :parent
+
+    def initialize(shape_element, parent)
+      @element = shape_element
+      @parent = parent
+    end
+
+    def ==(other) = other.is_a?(BaseShape) && other.element == @element
+    alias eql? ==
+
+    def hash = @element.hash
+
+    # The package part containing this shape.
+    def part = @parent.part
+
+    # The drawing-object id, unique within the slide.
+    def shape_id = @element.shape_id
+
+    def name = @element.shape_name
+
+    def name=(value)
+      @element.nvXxPr.cNvPr.name = value.to_s
+    end
+
+    # @return [Length, nil] nil when the shape inherits its position
+    def left = @element.x
+
+    def left=(value)
+      @element.x = value
+    end
+
+    def top = @element.y
+
+    def top=(value)
+      @element.y = value
+    end
+
+    def width = @element.cx
+
+    def width=(value)
+      @element.cx = value
+    end
+
+    def height = @element.cy
+
+    def height=(value)
+      @element.cy = value
+    end
+
+    # Clockwise rotation in degrees.
+    def rotation = @element.rot
+
+    def rotation=(value)
+      @element.rot = value
+    end
+
+    def placeholder? = @element.placeholder?
+
+    # This shape's shadow. Always returned, even when the shadow is inherited.
+    #
+    # @return [ShadowFormat]
+    def shadow = @shadow ||= ShadowFormat.new(@element.spPr)
+
+    # What happens when this shape is clicked during a slide show.
+    def click_action = @click_action ||= ActionSetting.new(@element.nvXxPr.cNvPr, self)
+
+    # What happens when the pointer rests on this shape.
+    def hover_action
+      @hover_action ||= ActionSetting.new(@element.nvXxPr.cNvPr, self, hover: true)
+    end
+
+    # The URL this shape links to, or nil.
+    #
+    # A shortcut for `click_action.url`, which is the common case; reach for
+    # {#click_action} when the click does something else. Nil when the click
+    # is not a hyperlink -- a slide jump reports nil here, not a partname.
+    def hyperlink = click_action.url
+
+    def hyperlink=(url)
+      click_action.address = url
+    end
+
+    # Placeholder position and type, or nil when this is not a placeholder.
+    def placeholder_format
+      placeholder? ? PlaceholderFormat.new(@element.ph) : nil
+    end
+
+    # Overridden by the subclasses that can actually hold these.
+    def text_frame? = false
+    def chart? = false
+    def table? = false
+
+    # @return [Pptx::Enum::MSO_SHAPE_TYPE]
+    def shape_type = raise(NotImplementedError, "#{self.class} must implement #shape_type")
+
+    def inspect = "#<#{self.class.name} id=#{shape_id} #{name.inspect}>"
+  end
+
+  # The placeholder-specific properties of a shape: which placeholder it is
+  # and what kind.
+  class PlaceholderFormat < ElementProxy
+    include PatternMatching
+
+    pattern_keys :idx, :type
+
+    # The `idx` that ties a slide placeholder to the layout one it inherits
+    # from. The title placeholder is always 0.
+    def idx = @element.idx
+
+    # @return [Pptx::Enum::PP_PLACEHOLDER]
+    def type = @element.type
+
+    def orientation = @element.orient
+
+    def size = @element.sz
+
+    def inspect = "#<Pptx::PlaceholderFormat idx=#{idx} type=#{type}>"
+  end
+end

data/lib/ruby_pptx/shapes/freeform.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Pptx
+  # Builds a freeform shape from a sequence of pen movements.
+  #
+  # Coordinates are given in whatever units suit the drawing -- "local"
+  # coordinates -- and +scale+ says how many EMU one local unit is worth. That
+  # lets a shape be described in convenient numbers and placed at any size:
+  #
+  #   shape = slide.shapes.add_freeform(at: [Pptx.inches(1), Pptx.inches(1)],
+  #                                     scale: Pptx.inches(1).emu / 100.0) do |f|
+  #     f.line_to(100, 0)
+  #     f.line_to(50, 100)
+  #   end
+  #
+  # The shape's position and size follow from the path: the bounding box of
+  # the points drawn, placed at the origin given to {#convert_to_shape}.
+  class FreeformBuilder
+    include Enumerable
+
+    # One pen movement. `kind` is :move, :line or :close; a close carries no
+    # coordinates.
+    Operation = Data.define(:kind, :x, :y)
+
+    def initialize(shapes, start_x, start_y, x_scale, y_scale)
+      @shapes = shapes
+      @start_x = round(start_x)
+      @start_y = round(start_y)
+      @x_scale = x_scale
+      @y_scale = y_scale
+      @operations = []
+    end
+
+    def self.new_builder(shapes, start_x, start_y, scale)
+      x_scale, y_scale = scale.is_a?(Array) ? scale : [scale, scale]
+      new(shapes, start_x, start_y, x_scale, y_scale)
+    end
+
+    def each(&) = @operations.each(&)
+
+    def size = @operations.size
+
+    # Draw a straight line to (x, y).
+    #
+    # @return [self] so calls can be chained
+    def line_to(x, y)
+      @operations << Operation.new(:line, round(x), round(y))
+      self
+    end
+
+    # Lift the pen and continue from (x, y), starting a new contour.
+    def move_to(x, y)
+      @operations << Operation.new(:move, round(x), round(y))
+      self
+    end
+
+    # Join the current contour back to where it started.
+    def close
+      @operations << Operation.new(:close, nil, nil)
+      self
+    end
+
+    # Draw a line to each of +vertices+, optionally closing the contour.
+    #
+    # @param vertices [Array<Array(Numeric, Numeric)>]
+    def add_line_segments(vertices, close: true)
+      vertices.each { |x, y| line_to(x, y) }
+      self.close if close
+      self
+    end
+
+    # Turn the path into a shape, with the local origin placed at +origin_at+
+    # on the slide.
+    #
+    # May be called more than once to stamp the same geometry in several
+    # places.
+    #
+    # @return [Shape]
+    def convert_to_shape(origin_at: [0, 0])
+      origin_x, origin_y = origin_at.map { |value| Length.coerce(value).emu }
+      sp = @shapes.add_freeform_element(origin_x + left, origin_y + top, width, height)
+      path = sp.add_path(local_width, local_height)
+      path.move_to(*to_shape_space(@start_x, @start_y))
+      @operations.each { |operation| apply(operation, path) }
+      @shapes.build_shape(sp)
+    end
+
+    # The leftmost extent of the path, in local coordinates.
+    #
+    # The bounding box need not start at the local origin, so this is what the
+    # points are measured from.
+    def offset_x = drawn.map(&:x).push(@start_x).min
+
+    def offset_y = drawn.map(&:y).push(@start_y).min
+
+    def inspect = "#<Pptx::FreeformBuilder #{size} operations>"
+
+    private
+
+    # Coordinates may be given as floats for convenience; the format wants
+    # integers.
+    #
+    # Rounded half-to-even, because Python rounds that way and Ruby rounds
+    # half-up: a coordinate of 100.5 would otherwise land a unit away from
+    # where the reference implementation puts it.
+    def round(value) = value.round(half: :even)
+
+    # Operations that have a position; a close does not.
+    def drawn = @operations.reject { |operation| operation.kind == :close }
+
+    def local_width
+      xs = drawn.map(&:x).push(@start_x)
+      xs.max - xs.min
+    end
+
+    def local_height
+      ys = drawn.map(&:y).push(@start_y)
+      ys.max - ys.min
+    end
+
+    def width = (local_width * @x_scale).round
+
+    def height = (local_height * @y_scale).round
+
+    def left = (offset_x * @x_scale).round
+
+    def top = (offset_y * @y_scale).round
+
+    # Points inside a path are relative to the shape's top-left corner, not to
+    # the local origin.
+    def to_shape_space(x, y) = [x - offset_x, y - offset_y]
+
+    def apply(operation, path)
+      case operation.kind
+      when :move then path.move_to(*to_shape_space(operation.x, operation.y))
+      when :line then path.line_to(*to_shape_space(operation.x, operation.y))
+      when :close then path.close_contour
+      end
+    end
+  end
+end