prawnpdf/prawn — pull request #400 by cheba (2012-09-07 17:05:52+00:00)
Title: New gradients

**Note:** this is not considered to be finished.

## Preamble

I needed more advanced gradients than those implemented in the upstream Prawn. I knew PDF supports pretty advanced graphics but I needed just some diagonal axial gradients and some radial gradients. Neither of those are implemented in Prawn.

## So, what's in it?

### Axial gradients

Axial gradients are implemented in Prawn now. But the major flaw in the implementation is that you can do only vertical gradients with it. Current implementation is incapable of any other kind of gradients such as diagonal or horizontal. Also it introduces a concept of gradient bounding box which is not present in PDF file format. Also it's not implemented as such in Prawn too, the only thing it does is strikes the rectangle of that box. I think that functionality is out of scope of gradients.

So what changed:
* Arbitrary axial gradients (e.g. diagonal or horizontal). This is defined by two points: `from` and `to`.
* No misleading bounding boxes
* New API. More on that a bit later

### Radial gradients

This is new to Prawn. Radial gradients can be represented for simplicity as a series of circles. The series is made by moving center of the circle from one point to another while also changing radius of the circle and its color.

In short, they're cool and now you can have them.

## New API

Please note that I'm rather new to Prawn. I'm not aware of any API guidelines on this project and seek an advice on how to do it better. I see that Prawn took more functional approach to API. A series of calls to Document object builds actual document. But I have some methods that construct object that are meant to be used in further calls.

Example:

```ruby
Prawn::Document.generate("test.pdf") do
g = linear_gradient [0, 0], [100, 100], "ff0000", "0000ff"
fill_color g
fill_rectangle [0, 100], 100, 100
end
```

I've took this approach because page needs to have a reference to a gradient in order to use it. Also the same gradient can be used multiple times through the document on different pages. I think it's easier to pass only one argument repeatedly than four or six.

I'm open for suggestion if you know how to do it better.

## An apology to Wojciech Piekutowski (@wpiekutowski)

Dear @wpiekutowski, I've removed you file because I didn't see how I could save it. After all the edits I've made the only thing that have left after your file was only a copyright notice. I'd like to keep your name but new file have virtually no resemblance of yours. I'm open for suggestion on how to keep your name on the project.