Class: DynamicImage

Inherits:
DynamicImageElements::BlockElement show all
Defined in:
lib/dynamic_image.rb

Overview

DynamicImage provides interface to create an image in ruby code.

:include:../README_USAGE.rdoc

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from DynamicImageElements::BlockElement

#block, #height, #image, #table, #text, #width

Methods included from DynamicImageElements::ElementInterface

#final_size, #set_height, #set_width

Constructor Details

#initialize(options = {}, &block) ⇒ DynamicImage

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 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.



29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/dynamic_image.rb', line 29

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

Instance Attribute Details

#context ⇒ Object (readonly)

Gets original Cairo::Context of Cairo::ImageSurface object if width and height was given in options or it’s created from existing source.



11
12
13
 
# File 'lib/dynamic_image.rb', line 11

def context
  @context
end

Class Method Details

.from(source, options = {}, &block) ⇒ Object

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 Gdk::Pixbuf.formats as source. By default, “jpeg”, “png” and “ico” are possible file formats to load from, but more formats may be installed.



141
142
143
144
 
# File 'lib/dynamic_image.rb', line 141

def self.from(source, options = {}, &block) # :yields: block_element
  options[:from_source] = source
  DynamicImage.new options, &block
end

Instance Method Details

#canvas_border ⇒ Object

Gets left and bottom borders of drawing canvas



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/dynamic_image.rb', line 118

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

#destroy ⇒ Object

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.



236
237
238
239
 
# File 'lib/dynamic_image.rb', line 236

def destroy
  @surface.destroy if @surface
  @context.destroy if @context
end

#drawing_endless ⇒ Object

Gets index of drawing endless from canvas



229
230
231
 
# File 'lib/dynamic_image.rb', line 229

def drawing_endless #:nodoc:
  @drawing_endless
end

#save!(file = nil, options = {}, &block) ⇒ Object

Saves image into file or given IO object (you have to speficify :format option like file extension, f.e. png). 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 Gdk::Pixbuf.formats 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.



156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/dynamic_image.rb', line 156

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

#save_endless!(limit = 0, options = {}, &block) ⇒ Object

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. png) 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 Gdk::Pixbuf.formats 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



213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/dynamic_image.rb', line 213

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