interface.rb in prawn-icon-3.0.0

- old
+ new

@@ -17,11 +17,11 @@
   # methods. Keys map directly to a unicode character
   # within the font that produces a given icon. As a
   # rule, included icon keys should match the keys from
   # the font provider. The icon key mapping is specified
   # in the font's +legend_file+, which is a +YAML+ file
-  # located in Prawn::Icon::Base::FONTDIR/font/font.yml.
+  # located in {Prawn::Icon.configuration.font_directory}/font/font.yml.
   #
   # Prawn::Icon::
   #   Houses the methods and interfaces necessary for
   #   rendering icons to the Prawn::Document.
   #
@@ -36,10 +36,11 @@
   #   inline_format: true option. The input string is parsed
   #   once for <icon></icon> tags, then the output is provided
   #   to Prawn's internal formatted text parser.
   #
   class Icon
+    # @deprecated Use {Prawn::Icon.configuration.font_directory} instead
     FONTDIR = Icon::Base::FONTDIR
 
     module Interface
       # Set up and draw an icon on this document. This
       # method operates much like +Prawn::Text::Box+.
@@ -61,15 +62,14 @@
       #   pdf.icon '<icon color="0099FF">fas-user-circle</icon>',
       #   inline_format: true
       #
       def icon(key, opts = {})
         key = translate_key(key)
-        make_icon(key, opts).tap(&:render)
+        make_icon(key, opts).tap { |i| i && i.render }
       end
 
-      # Initialize a new icon object, but do
-      # not render it to the document.
+      # Initialize a new icon object.
       #
       # == Parameters:
       # key::
       #   Contains the key to a particular icon within
       #   a font family. If :inline_format is true,
@@ -88,13 +88,13 @@
         else
           Icon.new(key, self, opts)
         end
       end
 
-      # Initialize a new formatted text box containing
-      # icon information, but don't render it to the
-      # document.
+      # Render formatted icon content to the document from
+      # a string containing icons. Content will correctly
+      # transition to a new page when necessary.
       #
       # == Parameters:
       # text::
       #   Input text to be parsed initially for <icon>
       #   tags, then passed to Prawn's formatted text
@@ -105,13 +105,40 @@
       #   underlying text call.
       #
       def inline_icon(text, opts = {})
         parsed = Icon::Parser.format(self, text)
         content = Text::Formatted::Parser.format(parsed)
+        formatted_text(content, opts)
+      end
+
+      # Initialize a formatted icon box from an icon-conatining
+      # string. Content is not directly rendered to the document,
+      # instead a +Prawn::Text::Formatted::Box+ instance is returned
+      # that responds to the +render+ method.
+      #
+      # == Parameters:
+      # text::
+      #   Input text to be parsed initially for <icon>
+      #   tags, then passed to Prawn's formatted text
+      #   parser.
+      #
+      # opts::
+      #   A hash of options that may be supplied to the
+      #   underlying text call.
+      #
+      def formatted_icon_box(text, opts = {})
+        parsed = Icon::Parser.format(self, text)
+        content = Text::Formatted::Parser.format(parsed)
+        position = opts.fetch(:at) do
+          [
+            opts.fetch(:x) { bounds.left },
+            opts.fetch(:y) { cursor }
+          ]
+        end
         box_options = opts.merge(
           inline_format: true,
           document: self,
-          at: [bounds.left, cursor]
+          at: position
         )
         icon_box(content, box_options)
       end
 
       # Initialize a new Prawn::Icon, but don't render