Change API for wibox.drawable:find_widgets()

Instead of matrix_to_device and matrix_to_parent, this now provides the
full hierarchy instance managing the current widget.

In addition to x, y, width and height (which are an over-approximation
of the widget's extents on the drawable), this now also provides
widget_width and widget_height in the widget's local coordinate system.
These last two values are exact.

For example, the tooltip needs x/y/width/height while a widget that
wants to figure out which point on it was hit with a mouse press will
need widget_width and widget_height (together with the position argument
that is passed in with mouse::press).

I don't know how to document the return type of this function properly.
Hopefully just describing the structure of the resulting table is good
enough.

Signed-off-by: Uli Schlachter <psychon@znc.in>

lib/wibox/drawable.lua

@@ -173,9 +173,11 @@ local function find_widgets(_drawable, result, _hierarchy, x, y)
             0, 0, width, height)
         table.insert(result, {
             x = x3, y = y3, width = w3, height = h3,
-            drawable = _drawable, widget = _hierarchy:get_widget(),
-            matrix_to_device = _hierarchy:get_matrix_to_device(),
-            matrix_to_parent = _hierarchy:get_matrix_to_parent(),
+            widget_width = width,
+            widget_height = height,
+            drawable = _drawable,
+            widget = _hierarchy:get_widget(),
+            hierarchy = _hierarchy
         })
     end
     for _, child in ipairs(_hierarchy:get_children()) do
@@ -187,8 +189,14 @@ end
 -- The drawable must have drawn itself at least once for this to work.
 -- @param x X coordinate of the point
 -- @param y Y coordinate of the point
--- @return A sorted table with all widgets that contain the given point. The
---   widgets are sorted by relevance.
+-- @treturn table A table containing a description of all the widgets that
+-- contain the given point. Each entry is a table containing this drawable as
+-- its `.drawable` entry, the widget under `.widget` and the instance of
+-- `wibox.hierarchy` describing the size and position of the widget under
+-- `.hierarchy`. For convenience, `.x`, `.y`, `.width` and `.height` contain an
+-- approximation of the widget's extents on the surface. `widget_width` and
+-- `widget_height` contain the exact size of the widget in its own, local
+-- coordinate system (which may e.g. be rotated and scaled).
 function drawable:find_widgets(x, y)
     local result = {}
     if self._widget_hierarchy then