ruby_pptx 0.1.0

data/lib/ruby_pptx/text/text.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/pattern_matching"
+
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/dml/color"
+require "ruby_pptx/dml/fill"
+require "ruby_pptx/oxml/text"
+require "ruby_pptx/enum/text"
+require "ruby_pptx/action"
+require "ruby_pptx/text/fitter"
+
+module Pptx
+  # The text inside a shape.
+  #
+  # A text frame always holds at least one paragraph. Reading {#text} joins
+  # the paragraphs with "\n"; assigning it replaces everything.
+  #
+  #   frame = shape.text_frame
+  #   frame.text = "First line\nSecond line"
+  #   frame.paragraphs.first.runs.first.font.bold = true
+  class TextFrame
+    include PatternMatching
+
+    pattern_keys :text, :paragraphs, :word_wrap, :auto_size, :vertical_anchor
+
+    attr_reader :parent, :element
+
+    def initialize(tx_body, parent)
+      @element = tx_body
+      @parent = parent
+    end
+
+    def part = @parent.part
+
+    # The paragraphs of this text frame; there is always at least one.
+    #
+    # @return [Array<Paragraph>]
+    def paragraphs = @element.p_list.map { |p| Paragraph.new(p, self) }
+
+    # Append an empty paragraph and return it.
+    def add_paragraph = Paragraph.new(@element.add_p, self)
+
+    # All the text, with "\n" between paragraphs and "\v" for each soft line
+    # break.
+    def text = paragraphs.map(&:text).join("\n")
+
+    # Replace all text. Each "\n" starts a new paragraph, each "\v" a soft
+    # line break within one.
+    def text=(value)
+      @element.clear_content
+      value.to_s.split("\n", -1).each do |paragraph_text|
+        @element.add_p.append_text(paragraph_text)
+      end
+      @element.unclear_content
+    end
+
+    # Remove all text, leaving a single empty paragraph.
+    def clear
+      @element.clear_content
+      @element.unclear_content
+      self
+    end
+
+    def margin_left = body_properties.lIns
+
+    def margin_left=(value)
+      body_properties.lIns = value
+    end
+
+    def margin_right = body_properties.rIns
+
+    def margin_right=(value)
+      body_properties.rIns = value
+    end
+
+    def margin_top = body_properties.tIns
+
+    def margin_top=(value)
+      body_properties.tIns = value
+    end
+
+    def margin_bottom = body_properties.bIns
+
+    def margin_bottom=(value)
+      body_properties.bIns = value
+    end
+
+    # @return [Pptx::Enum::MSO_ANCHOR, nil] nil when inherited
+    def vertical_anchor = body_properties.anchor
+
+    def vertical_anchor=(value)
+      body_properties.anchor = value
+    end
+
+    # @return [Pptx::Enum::MSO_AUTO_SIZE, nil] nil when inherited
+    def auto_size = body_properties.autofit
+
+    def auto_size=(value)
+      body_properties.autofit = value
+    end
+
+    # True, false, or nil when the setting is inherited.
+    def word_wrap
+      case body_properties.wrap
+      when Oxml::SimpleTypes::ST_TextWrappingType::SQUARE then true
+      when Oxml::SimpleTypes::ST_TextWrappingType::NONE then false
+      end
+    end
+
+    def word_wrap=(value)
+      unless [true, false, nil].include?(value)
+        raise ArgumentError, "word_wrap must be true, false or nil, got #{value.inspect}"
+      end
+
+      body_properties.wrap =
+        case value
+        when true then Oxml::SimpleTypes::ST_TextWrappingType::SQUARE
+        when false then Oxml::SimpleTypes::ST_TextWrappingType::NONE
+        end
+    end
+
+    # Shrink the text until it fits the shape, and apply that size to all of it.
+    #
+    # Turns word wrap on and autofit off, then sets every run -- and the
+    # end-paragraph properties, so typing in PowerPoint continues in the same
+    # font -- to +font_family+ at the size found.
+    #
+    #   frame.fit_text(font_file: "/usr/share/fonts/.../DejaVuSans.ttf",
+    #                  font_family: "DejaVu Sans", max_size: 28)
+    #
+    # A +font_file+ is required: measuring needs the actual glyph outlines, and
+    # this gem does not go looking through system font directories for them.
+    # The size is measured from the font's own metrics rather than by
+    # rendering, so it can differ from python-pptx's by a point on text that
+    # only just fits; see PORTING.md.
+    #
+    # @return [Integer] the point size applied
+    def fit_text(font_file:, font_family: "Calibri", max_size: 18, bold: false, italic: false)
+      raise Error, "cannot fit text in a text frame with no text" if text.empty?
+
+      size = TextFitter.best_fit_font_size(text, extents: extents, max_size: max_size,
+                                                 font_file: font_file)
+      raise Error, "text does not fit at any size up to #{max_size}pt" if size.nil?
+
+      apply_fit(font_family, size, bold, italic)
+      size
+    end
+
+    # The area text actually gets to occupy: the shape less its margins.
+    #
+    # @return [Array(Integer, Integer)] width and height in EMU
+    def extents
+      [@parent.width - margin_left - margin_right, @parent.height - margin_top - margin_bottom]
+    end
+
+    def inspect = "#<Pptx::TextFrame #{text.inspect}>"
+
+    private
+
+    def apply_fit(family, size, bold, italic)
+      self.auto_size = Enum::MSO_AUTO_SIZE::NONE
+      self.word_wrap = true
+      each_character_properties do |properties|
+        font = Font.new(properties)
+        font.name = family
+        font.size = Pptx.pt(size)
+        font.bold = bold
+        font.italic = italic
+      end
+    end
+
+    # Every run in the frame, plus each paragraph's end-paragraph properties.
+    def each_character_properties
+      @element.p_list.each do |p|
+        p.content_children.each { |child| yield child.get_or_add_rPr }
+        yield p.get_or_add_endParaRPr
+      end
+    end
+
+    def body_properties = @element.bodyPr
+  end
+
+  # One paragraph of a text frame.
+  class Paragraph
+    include PatternMatching
+
+    pattern_keys :text, :runs, :level, :alignment
+
+    attr_reader :element, :parent
+
+    def initialize(p, parent)
+      @element = p
+      @parent = parent
+    end
+
+    def part = @parent.part
+
+    # @return [Array<Run>]
+    def runs = @element.r_list.map { |r| Run.new(r, self) }
+
+    def add_run(text = nil) = Run.new(@element.add_run(text), self)
+
+    def add_line_break
+      @element.add_line_break
+      self
+    end
+
+    # The text of this paragraph, with "\v" for each soft line break.
+    def text = @element.text
+
+    # Replace this paragraph's text, turning "\v" (or "\n") into line breaks
+    # rather than new paragraphs -- a paragraph cannot contain another.
+    def text=(value)
+      clear
+      @element.append_text(value)
+    end
+
+    # Remove the content, keeping the paragraph and its properties.
+    def clear
+      @element.content_children.each { |child| @element.remove(child) }
+      self
+    end
+
+    # @return [Pptx::Enum::PP_ALIGN, nil] nil when inherited
+    def alignment = paragraph_properties.algn
+
+    def alignment=(value)
+      paragraph_properties.algn = value
+    end
+
+    # Outline level, 0 for the top level.
+    def level = paragraph_properties.lvl
+
+    def level=(value)
+      paragraph_properties.lvl = value
+    end
+
+    # A Float is a number of lines; a {Pptx::Length} is a fixed distance.
+    def line_spacing = paragraph_properties.line_spacing
+
+    def line_spacing=(value)
+      paragraph_properties.line_spacing = value
+    end
+
+    def space_before = paragraph_properties.space_before
+
+    def space_before=(value)
+      paragraph_properties.space_before = value
+    end
+
+    def space_after = paragraph_properties.space_after
+
+    def space_after=(value)
+      paragraph_properties.space_after = value
+    end
+
+    # The default character formatting for runs in this paragraph.
+    def font = Font.new(paragraph_properties.get_or_add_defRPr)
+
+    def inspect = "#<Pptx::Paragraph #{text.inspect}>"
+
+    private
+
+    def paragraph_properties = @element.get_or_add_pPr
+  end
+
+  # A run: a span of text sharing one set of character properties.
+  class Run
+    include PatternMatching
+
+    pattern_keys :text, :font, :hyperlink
+
+    attr_reader :element, :parent
+
+    def initialize(r, parent)
+      @element = r
+      @parent = parent
+    end
+
+    def part = @parent.part
+
+    def text = @element.text
+
+    def text=(value)
+      @element.text = value
+    end
+
+    def font = Font.new(@element.get_or_add_rPr)
+
+    # What happens when this run of text is clicked.
+    def click_action = @click_action ||= ActionSetting.new(@element.get_or_add_rPr, self)
+
+    # The URL this run links to, or nil.
+    def hyperlink = click_action.url
+
+    def hyperlink=(url)
+      click_action.address = url
+    end
+
+    def inspect = "#<Pptx::Run #{text.inspect}>"
+  end
+
+  # Character formatting: typeface, size, weight, colour.
+  #
+  # Every property returns nil when the value is inherited from the style
+  # hierarchy rather than set here, and assigning nil restores that
+  # inheritance.
+  class Font
+    include PatternMatching
+
+    pattern_keys :name, :size, :bold, :italic, :underline
+
+    attr_reader :element
+
+    def initialize(r_pr)
+      @element = r_pr
+    end
+
+    def bold = @element.b
+
+    def bold=(value)
+      @element.b = value
+    end
+
+    def italic = @element.i
+
+    def italic=(value)
+      @element.i = value
+    end
+
+    # The typeface name, or nil when inherited from the theme.
+    def name = @element.latin&.typeface
+
+    def name=(value)
+      if value.nil?
+        @element.remove_latin
+      else
+        @element.get_or_add_latin.typeface = value
+      end
+    end
+
+    # @return [Pptx::Length, nil]
+    def size
+      centipoints = @element.sz
+      centipoints && Pptx::Length.centipoints(centipoints)
+    end
+
+    def size=(value)
+      @element.sz = value.nil? ? nil : Pptx::Length.coerce(value).centipoints
+    end
+
+    # true for a single underline, false for none, a
+    # {Pptx::Enum::MSO_UNDERLINE} member for anything fancier, nil when
+    # inherited.
+    def underline
+      value = @element.u
+      return nil if value.nil?
+      return false if value == Enum::MSO_UNDERLINE::NONE
+      return true if value == Enum::MSO_UNDERLINE::SINGLE_LINE
+
+      value
+    end
+
+    def underline=(value)
+      @element.u =
+        case value
+        when true then Enum::MSO_UNDERLINE::SINGLE_LINE
+        when false then Enum::MSO_UNDERLINE::NONE
+        else value
+        end
+    end
+
+    # @return [Pptx::Enum::MSO_LANGUAGE_ID, nil]
+    def language = @element.lang
+
+    def language=(value)
+      @element.lang = value
+    end
+
+    # The fill of the text itself.
+    def fill = @fill ||= FillFormat.from_fill_parent(@element)
+
+    # The text colour. Accessing it makes the fill solid, since a colour has
+    # to live on some fill.
+    def color
+      fill.solid if fill.type.nil?
+      fill.fore_color
+    end
+
+    def inspect = "#<Pptx::Font name=#{name.inspect} size=#{size&.pt} bold=#{bold.inspect}>"
+  end
+end

data/lib/ruby_pptx/theme.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/dml/color"
+require "ruby_pptx/oxml/theme"
+
+module Pptx
+  # The colours and fonts a slide master draws from.
+  #
+  #   theme = master.theme
+  #   theme.name = "Corporate"
+  #   theme.colors[:accent1].rgb = Pptx::RGBColor.from_string("1F497D")
+  #   theme.fonts.major = "Georgia"
+  #
+  # A theme also carries a *format* scheme -- the numbered fill, line and
+  # effect styles that shapes and slide backgrounds refer to by `idx`. Those
+  # are inherited from the base theme and not editable here; writing a
+  # coherent set by hand is a design exercise, not a configuration one.
+  class Theme < PartElementProxy
+    def name = @element.name
+
+    def name=(value)
+      # PowerPoint shows the theme name in three places and expects them to
+      # agree, so the schemes are renamed with it.
+      @element.name = value
+      @element.clrScheme.name = value
+      @element.fontScheme.name = value
+    end
+
+    # @return [ThemeColors]
+    def colors = @colors ||= ThemeColors.new(@element.clrScheme, self)
+
+    # @return [ThemeFonts]
+    def fonts = @fonts ||= ThemeFonts.new(@element.fontScheme, self)
+
+    def inspect = "#<Pptx::Theme #{name.inspect}>"
+  end
+
+  # The twelve theme colours, addressed by name.
+  #
+  #   theme.colors[:accent1].rgb = Pptx::RGBColor.from_string("C0504D")
+  #   theme.colors[:accent1].rgb   #=> #<Pptx::RGBColor C0504D>
+  #
+  # Each entry is an ordinary {Pptx::ColorFormat}, so it takes an explicit RGB
+  # value the same way any other colour in the library does.
+  class ThemeColors < ParentedElementProxy
+    include Enumerable
+
+    # The names, in the order PowerPoint lists them.
+    NAMES = Oxml::CT_ColorScheme::SLOTS.map(&:to_sym).freeze
+
+    # @return [Pptx::ColorFormat]
+    def [](name) = ColorFormat.from_color_choice_parent(@element.slot(name))
+
+    def each
+      return enum_for(:each) { NAMES.size } unless block_given?
+
+      NAMES.each { |name| yield name, self[name] }
+      self
+    end
+
+    # Set several at once, which is how a palette is usually handed over.
+    #
+    #   theme.colors.update(accent1: "1F497D", accent2: "C0504D")
+    #
+    # Values may be {Pptx::RGBColor} or a hex string.
+    def update(**colors)
+      colors.each do |name, value|
+        self[name].rgb = value.is_a?(RGBColor) ? value : RGBColor.from_string(value.to_s)
+      end
+      self
+    end
+
+    def names = NAMES
+
+    def inspect = "#<Pptx::ThemeColors #{NAMES.size} colours>"
+  end
+
+  # The heading and body typefaces of a theme.
+  #
+  # PowerPoint calls these "major" and "minor"; they are what `+mj-lt` and
+  # `+mn-lt` resolve to in placeholder text.
+  class ThemeFonts < ParentedElementProxy
+    def major = @element.majorFont.typeface
+
+    def major=(value)
+      @element.majorFont.typeface = value
+    end
+
+    def minor = @element.minorFont.typeface
+
+    def minor=(value)
+      @element.minorFont.typeface = value
+    end
+
+    def inspect = "#<Pptx::ThemeFonts major=#{major.inspect} minor=#{minor.inspect}>"
+  end
+end

data/lib/ruby_pptx/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pptx
+  VERSION = "0.1.0"
+end

data/lib/ruby_pptx.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "zip"
+
+require "ruby_pptx/version"
+require "ruby_pptx/errors"
+require "ruby_pptx/length"
+require "ruby_pptx/geometry"
+require "ruby_pptx/oxml/ns"
+require "ruby_pptx/oxml/simple_types"
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/opc/pack_uri"
+require "ruby_pptx/opc/constants"
+require "ruby_pptx/opc/spec"
+require "ruby_pptx/opc/oxml"
+require "ruby_pptx/opc/serialized"
+require "ruby_pptx/opc/package"
+
+require "ruby_pptx/sliceable"
+require "ruby_pptx/pattern_matching"
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/oxml/presentation"
+require "ruby_pptx/oxml/slide"
+require "ruby_pptx/oxml/core_properties"
+require "ruby_pptx/oxml/dml/color"
+require "ruby_pptx/oxml/dml/fill"
+require "ruby_pptx/oxml/text"
+require "ruby_pptx/dml/color"
+require "ruby_pptx/dml/fill"
+require "ruby_pptx/dml/effect"
+require "ruby_pptx/oxml/theme"
+require "ruby_pptx/theme"
+require "ruby_pptx/text/text"
+require "ruby_pptx/text/font_metrics"
+require "ruby_pptx/text/fitter"
+require "ruby_pptx/oxml/table"
+require "ruby_pptx/oxml/chart"
+require "ruby_pptx/chart/data"
+require "ruby_pptx/chart/workbook_writer"
+require "ruby_pptx/chart/xy_data"
+require "ruby_pptx/chart/xml_writer"
+require "ruby_pptx/chart/format"
+require "ruby_pptx/chart/combo"
+require "ruby_pptx/chart/chart"
+require "ruby_pptx/image"
+require "ruby_pptx/media"
+require "ruby_pptx/oxml/action"
+require "ruby_pptx/action"
+require "ruby_pptx/oxml/shapes/shared"
+require "ruby_pptx/oxml/shapes/autoshape"
+require "ruby_pptx/oxml/shapes/groupshape"
+require "ruby_pptx/oxml/shapes/other"
+require "ruby_pptx/autoshape_spec"
+require "ruby_pptx/shapes/base"
+require "ruby_pptx/shapes/shape"
+require "ruby_pptx/shapes/placeholder"
+require "ruby_pptx/shapes/freeform"
+require "ruby_pptx/shapes/adjustments"
+require "ruby_pptx/shapes/authoring"
+require "ruby_pptx/shapes/shape_tree"
+require "ruby_pptx/oxml/section"
+require "ruby_pptx/slide"
+require "ruby_pptx/section"
+require "ruby_pptx/table_paging"
+require "ruby_pptx/builder"
+require "ruby_pptx/presentation"
+require "ruby_pptx/parts/core_properties"
+require "ruby_pptx/parts/image"
+require "ruby_pptx/parts/media"
+require "ruby_pptx/parts/chart"
+require "ruby_pptx/parts/slide"
+require "ruby_pptx/parts/presentation"
+require "ruby_pptx/parts/theme"
+require "ruby_pptx/parts/embedded_package"
+require "ruby_pptx/package"
+
+require "ruby_pptx/enum/base"
+require "ruby_pptx/enum/action"
+require "ruby_pptx/enum/chart"
+require "ruby_pptx/enum/dml"
+require "ruby_pptx/enum/lang"
+require "ruby_pptx/enum/shapes"
+require "ruby_pptx/enum/text"
+require "ruby_pptx/enum/prog_id"
+
+# A Ruby object model for PowerPoint (.pptx) files, ported from python-pptx.
+module Pptx
+end