dynamic_images 1.0.0

data/Manifest

@@ -0,0 +1,27 @@
+README.rdoc
+README_USAGE.rdoc
+Rakefile
+examples/gtk_window.rb
+examples/named_colors_table.rb
+init.rb
+lib/dynamic_image.rb
+lib/elements/block_element.rb
+lib/elements/element_interface.rb
+lib/elements/image_element.rb
+lib/elements/table_cell_element.rb
+lib/elements/table_element.rb
+lib/elements/text_element.rb
+lib/parsers/xml.dtd
+lib/parsers/xml_parser.rb
+lib/render_image.rb
+lib/sources/color_source.rb
+lib/sources/gradient_source.rb
+lib/sources/source_factory.rb
+test/asym.rb
+test/performance.1.rb
+test/performance.2.rb
+test/performance.3.rb
+test/performance.rb
+test/units1.rb
+test/units2.rb
+Manifest

data/README.rdoc

@@ -0,0 +1,104 @@
+= Dynamic Images
+
+Ruby library providing image rendering described by dynamic templates
+
+== Dependencies
+
+Library is using these libraries:
+* cairo
+* pango
+* rexml
+
+== How to install & use
+
+Download this repository and place it into your folder.
+
+Require init.rb file from library's folder.
+
+Optionaly you can load gtk2 libraty too. It's supporting another image formats.
+
+For more information how to use or about elements read documentation.
+
+
+
+
+= Usage of Library
+
+== In general about options
+Options should be in base given as hash. Format of keys in hash is not fixed. You can use +Symbol+ as good as +String+. There is also no difference between "-" and "_" chars.
+
+If option accepts more arguments you can specify they in +Array+ and also in +String+. In case you choose +String+ it's necessary to seperate arguments by space char.
+
+=== Example
+These <tt>Hash</tt>es are considered as absolutelly same.
+* <tt>{:vertical_align => :middle}</tt>, <tt>{'vertical_align' => 'middle'}</tt>, <tt>{"vertical-align" => :middle}</tt>, <tt>{:vertical_align => "middle"}</tt>, <tt>{:vertical_align => :middle}</tt>, etc.
+* <tt>{:to_fit => [:crop, :sentences, 3, :resize]}</tt>, <tt>{:to_fit => "crop sentences 3 resize"}</tt>, <tt>{'to-fit' => "crop sentences 3 resize"}</tt>, etc.
+
+== Passing a Block
+In block you can accept object to call methods on it or if you don't accept any argument, block is called in object instance.
+
+=== Example
+These examples are considered as same.
+  DynamicImage.new do |img|
+    img.text "<b>Warning</b>"
+    img.save! "warning.png"
+  end
+
+  DynamicImage.new do
+    text "<b>Warning</b>"
+    save! "warning.png"
+  end
+
+== Image formats
+In base you can save and load all as PNG images. You can enable more formats by loading gtk library. DynamicImage will automatically detect it's loaded.
+
+  require 'gtk2'
+
+== Using with Rails
+To use within Rails application just download this library as plugin.
+
+  rails plugin install git://github.com/malis/dynamic_images.git
+
+You need to add <tt>cairo</tt> and <tt>pango</tt> gems to your Gemfile or environment.rb file.
+
+Then just update your controller like this:
+
+  def show
+    @article = Article.find(params[:id])
+    respond_to do |format|
+      format.html
+      format.png { render_image } #or render_image("show.jpg"), find more in doc
+    end
+  end
+
+Do not forgot to add mime types for used image formats to your environment file.
+
+  Mime::Type.register "image/png", :png
+
+Create view articles/show.png.xml.erb like this:
+
+  <?xml version="1.0" encoding="UTF-8" ?>
+  <!DOCTYPE dynamic_images PUBLIC "-//malis//dynamic_images//EN" "https://raw.github.com/malis/dynamic_images/master/lib/parsers/xml.dtd">
+  <dynamic_images>
+    <dynamic_image width="500" align="center" background="blue 0.5">
+      <text font="Arial bold 20"><%= @article.title %></text>
+      <text indent="30"><%= @article.text %></text>
+    </dynamic_image>
+  </dynamic_images>
+
+That's all!
+
+Library is tested under Rails 2.3.11 (ruby 1.8.7) and 3.1.1 (ruby 1.9.2)
+
+
+
+
+
+
+
+
+== Copying
+Copyright (c) 2012 Dominik Mališ
+
+This program is free software.
+You can distribute/modify this program under the terms of the GNU LESSER GENERAL PUBLIC LICENSE.

data/README_USAGE.rdoc

@@ -0,0 +1,67 @@
+= Usage of Library
+
+== In general about options
+Options should be in base given as hash. Format of keys in hash is not fixed. You can use +Symbol+ as good as +String+. There is also no difference between "-" and "_" chars.
+
+If option accepts more arguments you can specify they in +Array+ and also in +String+. In case you choose +String+ it's necessary to seperate arguments by space char.
+
+=== Example
+These <tt>Hash</tt>es are considered as absolutelly same.
+* <tt>{:vertical_align => :middle}</tt>, <tt>{'vertical_align' => 'middle'}</tt>, <tt>{"vertical-align" => :middle}</tt>, <tt>{:vertical_align => "middle"}</tt>, <tt>{:vertical_align => :middle}</tt>, etc.
+* <tt>{:to_fit => [:crop, :sentences, 3, :resize]}</tt>, <tt>{:to_fit => "crop sentences 3 resize"}</tt>, <tt>{'to-fit' => "crop sentences 3 resize"}</tt>, etc.
+
+== Passing a Block
+In block you can accept object to call methods on it or if you don't accept any argument, block is called in object instance.
+
+=== Example
+These examples are considered as same.
+  DynamicImage.new do |img|
+    img.text "<b>Warning</b>"
+    img.save! "warning.png"
+  end
+
+  DynamicImage.new do
+    text "<b>Warning</b>"
+    save! "warning.png"
+  end
+
+== Image formats
+In base you can save and load all as PNG images. You can enable more formats by loading gtk library. DynamicImage will automatically detect it's loaded.
+
+  require 'gtk2'
+
+== Using with Rails
+To use within Rails application just download this library as plugin.
+
+  rails plugin install git://github.com/malis/dynamic_images.git
+
+You need to add <tt>cairo</tt> and <tt>pango</tt> gems to your Gemfile or environment.rb file.
+
+Then just update your controller like this:
+
+  def show
+    @article = Article.find(params[:id])
+    respond_to do |format|
+      format.html
+      format.png { render_image } #or render_image("show.jpg"), find more in doc
+    end
+  end
+
+Do not forgot to add mime types for used image formats to your environment file.
+
+  Mime::Type.register "image/png", :png
+
+Create view articles/show.png.xml.erb like this:
+
+  <?xml version="1.0" encoding="UTF-8" ?>
+  <!DOCTYPE dynamic_images PUBLIC "-//malis//dynamic_images//EN" "https://raw.github.com/malis/dynamic_images/master/lib/parsers/xml.dtd">
+  <dynamic_images>
+    <dynamic_image width="500" align="center" background="blue 0.5">
+      <text font="Arial bold 20"><%= @article.title %></text>
+      <text indent="30"><%= @article.text %></text>
+    </dynamic_image>
+  </dynamic_images>
+
+That's all!
+
+Library is tested under Rails 2.3.11 (ruby 1.8.7) and 3.1.1 (ruby 1.9.2)

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('dynamic_images', '1.0.0') do |p|
+  p.description    = "Ruby library providing image rendering described by dynamic templates"
+  p.url            = "http://github.com/malis/dynamic_images"
+  p.author         = "Dominik Malis"
+  p.email          = "dominik.malis@gmail.com"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.runtime_dependencies = ["cairo", "pango"]
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/dynamic_images.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "dynamic_images"
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Dominik Malis"]
+  s.date = "2012-06-19"
+  s.description = "Ruby library providing image rendering described by dynamic templates"
+  s.email = "dominik.malis@gmail.com"
+  s.extra_rdoc_files = ["README.rdoc", "README_USAGE.rdoc", "lib/dynamic_image.rb", "lib/elements/block_element.rb", "lib/elements/element_interface.rb", "lib/elements/image_element.rb", "lib/elements/table_cell_element.rb", "lib/elements/table_element.rb", "lib/elements/text_element.rb", "lib/parsers/xml.dtd", "lib/parsers/xml_parser.rb", "lib/render_image.rb", "lib/sources/color_source.rb", "lib/sources/gradient_source.rb", "lib/sources/source_factory.rb"]
+  s.files = ["README.rdoc", "README_USAGE.rdoc", "Rakefile", "examples/gtk_window.rb", "examples/named_colors_table.rb", "init.rb", "lib/dynamic_image.rb", "lib/elements/block_element.rb", "lib/elements/element_interface.rb", "lib/elements/image_element.rb", "lib/elements/table_cell_element.rb", "lib/elements/table_element.rb", "lib/elements/text_element.rb", "lib/parsers/xml.dtd", "lib/parsers/xml_parser.rb", "lib/render_image.rb", "lib/sources/color_source.rb", "lib/sources/gradient_source.rb", "lib/sources/source_factory.rb", "test/asym.rb", "test/performance.1.rb", "test/performance.2.rb", "test/performance.3.rb", "test/performance.rb", "test/units1.rb", "test/units2.rb", "Manifest", "dynamic_images.gemspec"]
+  s.homepage = "http://github.com/malis/dynamic_images"
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Dynamic_images", "--main", "README_USAGE.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "dynamic_images"
+  s.rubygems_version = "1.8.10"
+  s.summary = "Ruby library providing image rendering described by dynamic templates"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<cairo>, [">= 0"])
+      s.add_runtime_dependency(%q<pango>, [">= 0"])
+    else
+      s.add_dependency(%q<cairo>, [">= 0"])
+      s.add_dependency(%q<pango>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<cairo>, [">= 0"])
+    s.add_dependency(%q<pango>, [">= 0"])
+  end
+end

data/examples/gtk_window.rb

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'gtk2'
+require File.dirname(__FILE__) + '/../init.rb'
+
+class Win < Gtk::Window
+  def initialize
+    super
+    set_title "DynamicImage Gtk Test"
+    signal_connect "destroy" do
+      Gtk.main_quit
+    end
+    resize 300, 300
+
+    @darea = Gtk::DrawingArea.new
+    @darea.signal_connect "expose-event" do
+      expose
+    end
+    add @darea
+
+    show_all
+  end
+
+  private
+  def expose
+    w = allocation.width
+    h = allocation.height
+
+    DynamicImage.from @darea.window.create_cairo_context do
+      block :w => w, :h => h, :bg => [:gradient_radial_repeat, "225deg", "50%", "0%", :lime, "50%", :red, "100%", :orange], :align => :center, :valign => :middle do
+        text "Try to resize me!", :font => "Arial bold 48", :color => [:gradient_repeat, "0%", :blue, "100%", :yellow]
+      end
+      save!
+    end
+  end
+end
+
+Gtk.init
+window = Win.new
+Gtk.main

data/examples/named_colors_table.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require File.dirname(__FILE__) + '/../init.rb'
+
+DynamicImage.new do
+  table :cols => 9 do
+    for color in DynamicImageSources::ColorSource.named_colors
+      cell :padding => 5, :margin => 2, :background => color do
+        text color
+      end
+    end
+  end
+  save! "named_colors_table.png"
+end

data/init.rb

@@ -0,0 +1,6 @@
+require File.dirname(__FILE__) + '/lib/dynamic_image.rb'
+
+if defined? ActionController::Base
+  require File.dirname(__FILE__) + '/lib/render_image.rb'
+  ActionController::Base.send :include, RenderImage
+end

data/lib/dynamic_image.rb

@@ -0,0 +1,240 @@
+require 'cairo'
+require 'pango'
+require File.dirname(__FILE__) + '/elements/block_element.rb'
+require File.dirname(__FILE__) + '/parsers/xml_parser.rb'
+
+# DynamicImage provides interface to create an image in ruby code.
+#
+# :include:../README_USAGE.rdoc
+class DynamicImage < DynamicImageElements::BlockElement
+  # Gets original Cairo::Context of Cairo::ImageSurface object if width and height was given in options or it's created from existing source.
+  attr_reader :context
+
+  # DynamicImage accepts options +Hash+. If block is given destroy method is called automatically after a block if source of image isn't Cairo object. Otherwise you have to call destroy manually.
+  #
+  # === Options
+  # Image accepts also all options like BlockElement. See it first.
+  #
+  # [:auto_destroy]
+  #   Sets whether to automatically destroy surface if you are using block. Default is true.
+  #
+  # [:format]
+  #   Sets the memory format of image data.
+  #
+  #   Valid values are :a1, :a8, :rgb24 and :argb32. See http://www.cairographics.org/manual/cairo-Image-Surfaces.html#cairo-format-t for details.
+  #
+  # [:from_source]
+  #   Creates new DynamicImage from given source if it's supported. It has same behavior as DynamicImage.from.
+  #
+  def initialize(options = {}, &block) # :yields: block_element
+    treat_options options
+    @options = options
+    use_options :margin
+    use_options :padding
+    if options[:width] && options[:height] || options[:from_source]
+      [:width, :height].each {|key| @options[key] = nil } if options[:from_source] #remove forbidden options
+      create_surface
+    end
+    super options, &block
+    destroy_by_block if block
+  end
+
+  private
+  def create_surface(use_from_source = true)
+    if @options[:from_source] && use_from_source
+      if @options[:from_source].is_a? Cairo::Surface
+        set_surface_and_context @options[:from_source]
+         @options[:auto_destroy] = false
+      elsif @options[:from_source].is_a? Cairo::Context
+        set_surface_and_context nil, @options[:from_source]
+        @options[:auto_destroy] = false
+      elsif @options[:from_source].to_s =~ /\.png$/i
+        image = Cairo::ImageSurface.from_png @options[:from_source]
+        set_surface_and_context image
+        set_width image.width, false
+        set_height image.height, false
+      else
+        if defined? Gdk
+          pixbuf = Gdk::Pixbuf.new @options[:from_source]
+          set_width pixbuf.width, false
+          set_height pixbuf.height, false
+          create_surface false
+          context.save
+          context.set_source_pixbuf pixbuf, 0, 0
+          context.rectangle 0, 0, pixbuf.width, pixbuf.height
+          context.clip
+          context.paint
+          context.restore
+        else
+          raise "Unsupported source format of: #{@options[:from_source]}"
+        end
+      end
+    else
+      w, h = @options[:width].to_i, @options[:height].to_i
+      if @padding
+        w += @padding[1] + @padding[3]
+        h += @padding[0] + @padding[2]
+      end
+      if @margin
+        w += @margin[1] + @margin[3]
+        h += @margin[0] + @margin[2]
+      end
+      if @border && !@border.empty?
+        w += @border[:left][0].to_i if @border[:left]
+        w += @border[:right][0].to_i if @border[:right]
+        h += @border[:top][0].to_i if @border[:top]
+        h += @border[:bottom][0].to_i if @border[:bottom]
+      end
+      surface_args = [w, h]
+      surface_args.unshift({
+        :a1 => Cairo::Format::A1,
+        :a8 => Cairo::Format::A8,
+        :rgb24 => Cairo::Format::RGB24,
+        :argb32 => Cairo::Format::ARGB32
+      }[@options[:format].to_sym]) if @options[:format]
+      @surface = Cairo::ImageSurface.new *surface_args
+      @context = Cairo::Context.new @surface
+      @context.set_antialias({
+        :default => Cairo::ANTIALIAS_DEFAULT,
+        :gray => Cairo::ANTIALIAS_GRAY,
+        :none => Cairo::ANTIALIAS_NONE,
+        :subpixel => Cairo::ANTIALIAS_SUBPIXEL
+      }[@options[:antialias].to_sym]) if @options[:antialias]
+    end
+  end
+
+  def set_surface_and_context(surface, context = nil)
+    @surface = surface
+    @context = context || Cairo::Context.new(surface)
+  end
+
+  # Call this if block is given to destroy surface
+  def destroy_by_block
+    self.destroy if @options[:auto_destroy] != false
+  end
+
+  public
+  # Gets left and bottom borders of drawing canvas
+  def canvas_border
+    x, y = [@options[:width], @options[:height]]
+    if @padding
+      x += @padding[3]
+      y += @padding[0]
+    end
+    if @margin
+      x += @margin[3]
+      y += @margin[0]
+    end
+    if @border && !@border.empty?
+      x += @border[:left][0].to_i if @border[:left]
+      y += @border[:top][0].to_i if @border[:top]
+    end
+    [x, y]
+  end
+
+  # Creates new DynamicImage from given source if it's supported. Use it in same way as DynamicImage.new.
+  #
+  # PNG is always supported as source.
+  #
+  # If there is +Gdk+ loaded you can use any from <tt>Gdk::Pixbuf.formats</tt> as source. By default, "jpeg", "png" and "ico" are possible file formats to load from, but more formats may be installed.
+  #
+  def self.from(source, options = {}, &block) # :yields: block_element
+    options[:from_source] = source
+    DynamicImage.new options, &block
+  end
+
+  # Saves image into file or given IO object (you have to speficify :format option like file extension, f.e. <tt>png</tt>). Image will be drawed only if no file is given. It's usable when you drawing into prepared Cairo object.
+  #
+  # Block can be given to draw into context directly.
+  #
+  # PNG format is always supported.
+  #
+  # If there is +Gdk+ loaded you can use any from <tt>Gdk::Pixbuf.formats</tt> as source. By default, "jpeg", "png" and "ico" are possible file formats to save in, but more formats may be installed.
+  #
+  # When saving into JPEG format you can pass :quality into options. Valid values are in 0 - 100.
+  #
+  def save!(file = nil, options = {}, &block) # :yields: context
+    treat_options options
+    unless context
+      canvas_size = final_size
+      canvas_size[0] = @options[:width] if @options[:width]
+      canvas_size[1] = @options[:height] if @options[:height]
+      set_width canvas_size[0], false
+      set_height canvas_size[1], false
+      create_surface
+    end
+    draw!
+    block.call context if block
+    write_to file, options if file
+  end
+
+  private
+  def write_to(file, options)
+    ext = options[:format]
+    ext ||= file.scan(/\.([a-z]+)$/i).flatten.first.downcase
+    if ext.to_s == "png"
+      context.target.write_to_png file
+    else
+      raise "Unsupported file type #{ext}" unless defined? Gdk
+      w, h = @options[:width], @options[:height]
+      pixmap = Gdk::Pixmap.new nil, w, h, 24
+      context = pixmap.create_cairo_context
+      context.set_source @context.target, 0, 0
+      context.paint
+      #pixbuf = Gdk::Pixbuf.new gtk.gdk.COLORSPACE_RGB, True, 8, w, h
+      pixbuf = Gdk::Pixbuf.from_drawable Gdk::Colormap.system, pixmap, 0, 0, w, h
+      begin
+        format = Gdk::Pixbuf.formats.select{|f| f.extensions.include? ext.to_s}.first.name
+      rescue
+        raise "Unsupported file type #{ext}"
+      end
+      pixbuf.save file, format, (format == "jpeg" && options[:quality] ? {'quality' => options[:quality]} : {})
+    end
+  end
+
+  public
+  # Saves image content into more images if content is bigger than given image size.
+  # Image is cut between elements in first level of elements hierarchy. In case of table it's cut between rows of table.
+  #
+  # Method accepts limit of pages to be rendered. If no number is given or 0 is passed it's not limited.
+  # Give a block returning filename or given IO object (you have to speficify :format option like file extension, f.e. <tt>png</tt>) to saving in it. Block provides index of page which is currently rendered. Index starting at 0.
+  #
+  # PNG format is always supported.
+  #
+  # If there is +Gdk+ loaded you can use any from <tt>Gdk::Pixbuf.formats</tt> as source. By default, "jpeg", "png" and "ico" are possible file formats to save in, but more formats may be installed.
+  #
+  # When saving into JPEG format you can pass :quality into options. Valid values are in 0 - 100.
+  #
+  # === Example
+  #  save_endless 4 do |index|
+  #    "image-#{index}.png"
+  #  end
+  #
+  def save_endless!(limit = 0, options = {}, &block) # :yields: index
+    raise "Width and height must be set when you saving endless" unless @options[:width] || @options[:height]
+    treat_options options
+    @drawing_endless = index = 0
+    loop do
+      draw! 0, 0, index
+      write_to block.call(index), options
+      destroy
+      create_surface
+      index += 1
+      @drawing_endless = index
+      break if index == limit || is_drawed?
+    end
+  end
+
+  # Gets index of drawing endless from canvas
+  def drawing_endless #:nodoc:
+    @drawing_endless
+  end
+
+  # Destroys source objects to free a memory. It's important to call this method when it's finished to avoid a memory leaks.
+  #
+  # If you passed a block to DynamicImage.new or DynamicImage.from it's called automatically after block is finished.
+  def destroy
+    @surface.destroy if @surface
+    @context.destroy if @context
+  end
+end