add Rectangle::vertical_fraction() as a convenience method

Conflicts:
	libs/canvas/rectangle.cc

libs/canvas/canvas/rectangle.h

@@ -64,6 +64,17 @@ public:
 	void set_x1 (Coord);
 	void set_y1 (Coord);
 
+        /** return @param y as a floating point fraction of the overall
+         *  height of the rectangle. @param y is in canvas coordinate space.
+         * 
+         *  A value of zero indicates that y is at the bottom of the
+         *  rectangle; a value of 1 indicates that y is at the top.
+         *
+         *  Will return zero if there is no bounding box or if y
+         *  is outside the bounding box.
+         */
+        double vertical_fraction (double y) const;
+
 	enum What {
 		NOTHING = 0x0,
 		LEFT = 0x1,

libs/canvas/rectangle.cc

@@ -266,3 +266,23 @@ Rectangle::set_outline_what (What what)
 		end_visual_change ();
 	}
 }
+
+double
+Rectangle::vertical_fraction (double y) const
+{
+        /* y is in canvas coordinates */
+
+        Duple i (canvas_to_item (Duple (0, y)));
+        boost::optional<Rect> r = bounding_box();
+        if (!r) {
+                return 0; /* not really correct, but what else can we do? */
+        }
+
+        Rect bbox (r.get());
+
+        if (i.y < bbox.y0 || i.y >= bbox.y1) {
+                return 0;
+        }
+
+        return (i.y - bbox.y0) / bbox.height();
+}