tests: Add images to the tooltip documentation

It also add some properties such as `border_width`, `border_color`
and `preferred_alignments`.

It also fix a documentation bug where the `margin_topleft` was called
`margins_topleft`. To conform to the documentation, both are now valid
but one should be removed the next time the API changes.

Fixes #1978

lib/awful/tooltip.lua

@@ -10,13 +10,16 @@
 -- How to create a tooltip?
 -- ---
 --
---     myclock = wibox.widget.textclock("%T", 1)
---     myclock_t = awful.tooltip({
---         objects = { myclock },
---         timer_function = function()
---                 return os.date("Today is %A %B %d %Y\nThe time is %T")
---             end,
---         })
+-- @DOC_awful_tooltip_textclock_EXAMPLE@
+--
+-- Alternatively, you can use `mouse::enter` signal:
+--
+-- @DOC_awful_tooltip_textclock2_EXAMPLE@
+--
+-- How to create a tooltip without objects?
+-- ---
+--
+-- @DOC_awful_tooltip_mouse_EXAMPLE@
 --
 -- How to add the same tooltip to multiple objects?
 -- ---
@@ -229,6 +232,13 @@ end
 
 --- The horizontal alignment.
 --
+-- This is valid for the mouse mode only. For the outside mode, use
+-- `preferred_positions`.
+--
+-- @DOC_awful_tooltip_align_EXAMPLE@
+--
+-- @DOC_awful_tooltip_align2_EXAMPLE@
+--
 -- The following values are valid:
 --
 -- * top_left
@@ -242,6 +252,8 @@ end
 --
 -- @property align
 -- @see beautiful.tooltip_align
+-- @see mode
+-- @see preferred_positions
 
 --- The default tooltip alignment.
 -- @beautiful beautiful.tooltip_align
@@ -265,6 +277,9 @@ end
 
 --- The shape of the tooltip window.
 -- If the shape require some parameters, use `set_shape`.
+--
+-- @DOC_awful_tooltip_shape_EXAMPLE@
+--
 -- @property shape
 -- @see gears.shape
 -- @see set_shape
@@ -275,7 +290,6 @@ end
 -- @tparam gears.shape s The shape
 -- @see shape
 -- @see gears.shape
-
 function tooltip:set_shape(s)
     self.backgroundbox:set_shape(s)
 end
@@ -285,6 +299,14 @@ end
 -- close to the mouse cursor. It is also possible to place the tooltip relative
 -- to the widget geometry.
 --
+-- **mouse:**
+--
+-- @DOC_awful_tooltip_mode_EXAMPLE@
+--
+-- **outside:**
+--
+-- @DOC_awful_tooltip_mode2_EXAMPLE@
+--
 -- Valid modes are:
 --
 -- * "mouse": Next to the mouse cursor
@@ -306,8 +328,17 @@ end
 
 --- The preferred positions when in `outside` mode.
 --
+-- @DOC_awful_tooltip_preferred_positions_EXAMPLE@
+--
 -- If the tooltip fits on multiple sides of the drawable, then this defines the
--- priority
+-- priority.
+--
+-- The valid table values are:
+--
+-- * "top"
+-- * "right"
+-- * "left"
+-- * "bottom"
 --
 -- The default is:
 --
@@ -315,6 +346,9 @@ end
 --
 -- @property preferred_positions
 -- @tparam table preferred_positions The position, ordered by priorities
+-- @see align
+-- @see mode
+-- @see preferred_alignments
 
 function tooltip:get_preferred_positions()
     return self._private.preferred_positions or
@@ -327,6 +361,36 @@ function tooltip:set_preferred_positions(value)
     set_geometry(self)
 end
 
+--- The preferred alignment when using the `outside` mode.
+--
+-- The values of the table are ordered by priority, the first one that fits
+-- will be used.
+--
+-- **front:**
+--
+-- @DOC_awful_tooltip_preferred_alignment_EXAMPLE@
+--
+-- **middle:**
+--
+-- @DOC_awful_tooltip_preferred_alignment2_EXAMPLE@
+--
+-- **back:**
+--
+-- @DOC_awful_tooltip_preferred_alignment3_EXAMPLE@
+--
+-- The valid table values are:
+--
+-- * front
+-- * middle
+-- * back
+--
+-- The default is:
+--
+--    {"front", "back", "middle"}
+--
+-- @property preferred_alignments
+-- @param string
+-- @see preferred_positions
 
 function tooltip:get_preferred_alignments()
     return self._private.preferred_alignments or
@@ -383,6 +447,8 @@ end
 
 --- Set all margins around the tooltip textbox
 --
+-- @DOC_awful_tooltip_margins_EXAMPLE@
+--
 -- @property margins
 -- @tparam tooltip self A tooltip object
 -- @tparam number New margins value
@@ -391,11 +457,23 @@ function tooltip:set_margins(val)
     self.marginbox:set_margins(val)
 end
 
+--- The border width.
+--
+-- @DOC_awful_tooltip_border_width_EXAMPLE@
+--
+-- @property border_width
+-- @param number
 
 function tooltip:set_border_width(val)
     self.widget.shape_border_width = val
 end
 
+--- The border color.
+--
+-- @DOC_awful_tooltip_border_color_EXAMPLE@
+--
+-- @property border_color
+-- @param gears.color
 
 function tooltip:set_border_color(val)
     self.widget.shape_border_color = val
@@ -403,6 +481,8 @@ end
 
 --- Set the margins around the left and right of the tooltip textbox
 --
+-- @DOC_awful_tooltip_margins_leftright_EXAMPLE@
+--
 -- @property margins_leftright
 -- @tparam tooltip self A tooltip object
 -- @tparam number New margins value
@@ -419,6 +499,8 @@ end
 
 --- Set the margins around the top and bottom of the tooltip textbox
 --
+-- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@
+--
 -- @property margins_topbottom
 -- @tparam tooltip self A tooltip object
 -- @tparam number New margins value

tests/examples/awful/tooltip/align.lua

@@ -0,0 +1,30 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 300, height = 75}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+-- mouse.coords{x=50, y= 10}
+
+    local wb = wibox {
+        width = 100, height = 44, x = 100, y = 10, visible = true, bg = "#00000000"
+    }
+
+awesome.emit_signal("refresh")
+
+for _, side in ipairs{ "top_left", "bottom_left", "top_right", "bottom_right"} do
+    local tt = awful.tooltip {
+        text = side,
+        objects = {wb},
+        mode = "mouse",
+        align = side,
+    }
+    tt.bg = beautiful.bg_normal
+end
+
+mouse.coords{x=125, y= 35}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/align2.lua

@@ -0,0 +1,30 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 300, height = 75}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+-- mouse.coords{x=50, y= 10}
+
+    local wb = wibox {
+        width = 100, height = 44, x = 100, y = 10, visible = true, bg = "#00000000"
+    }
+
+awesome.emit_signal("refresh")
+
+for _, side in ipairs{ "left", "right", "bottom", "top" } do
+    local tt = awful.tooltip {
+        text = side,
+        objects = {wb},
+        mode = "mouse",
+        align = side,
+    }
+    tt.bg = beautiful.bg_normal
+end
+
+mouse.coords{x=125, y= 35}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/border_color.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 640, height = 55}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+
+-- mouse.coords{x=50, y= 10}
+
+awesome.emit_signal("refresh")
+
+local x_offset = 0
+
+for _, color in ipairs{ "#ff0000", "#00ff00", "#0000ff", "#00ffff" } do
+    local tt = awful.tooltip {
+        text = color,
+        mode = "mouse",
+        border_width = 2,
+        border_color = color,
+    }
+    tt.bg = beautiful.bg_normal
+    awesome.emit_signal("refresh")
+    tt:show()
+    awesome.emit_signal("refresh")
+    tt.wibox.x = x_offset
+    x_offset = x_offset + 640/5
+end
+
+mouse.coords{x=125, y= 0}
+-- mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/border_width.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 640, height = 55}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+
+-- mouse.coords{x=50, y= 10}
+
+awesome.emit_signal("refresh")
+
+local x_offset = 0
+
+for _, width in ipairs{ 1,2,4,6 } do
+    local tt = awful.tooltip {
+        text = "width: "..width,
+        mode = "mouse",
+        border_width = width,
+        border_color = beautiful.border_color,
+    }
+    tt.bg = beautiful.bg_normal
+    awesome.emit_signal("refresh")
+    tt:show()
+    awesome.emit_signal("refresh")
+    tt.wibox.x = x_offset
+    x_offset = x_offset + 640/5
+end
+
+mouse.coords{x=125, y= 0}
+-- mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/margins.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 640, height = 55}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+
+-- mouse.coords{x=50, y= 10}
+
+awesome.emit_signal("refresh")
+
+local x_offset = 0
+
+for _, width in ipairs{ 1,2,4,6 } do
+    local tt = awful.tooltip {
+        text = "margins: "..width,
+        mode = "mouse",
+        margins = width,
+        border_color = beautiful.border_color,
+    }
+    tt.bg = beautiful.bg_normal
+    awesome.emit_signal("refresh")
+    tt:show()
+    awesome.emit_signal("refresh")
+    tt.wibox.x = x_offset
+    x_offset = x_offset + 640/5
+end
+
+mouse.coords{x=125, y= 0}
+-- mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/margins_leftright.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 640, height = 55}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+
+-- mouse.coords{x=50, y= 10}
+
+awesome.emit_signal("refresh")
+
+local x_offset = 0
+
+for _, width in ipairs{ 1,2,4,6 } do
+    local tt = awful.tooltip {
+        text = "margins: "..width,
+        mode = "mouse",
+        margins_leftright = width,
+        border_color = beautiful.border_color,
+    }
+    tt.bg = beautiful.bg_normal
+    awesome.emit_signal("refresh")
+    tt:show()
+    awesome.emit_signal("refresh")
+    tt.wibox.x = x_offset
+    x_offset = x_offset + 640/5
+end
+
+mouse.coords{x=125, y= 0}
+-- mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/margins_topbottom.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 640, height = 55}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+
+-- mouse.coords{x=50, y= 10}
+
+awesome.emit_signal("refresh")
+
+local x_offset = 0
+
+for _, width in ipairs{ 1,2,4,6 } do
+    local tt = awful.tooltip {
+        text = "margins: "..width,
+        mode = "mouse",
+        margins_topbottom = width,
+        border_color = beautiful.border_color,
+    }
+    tt.bg = beautiful.bg_normal
+    awesome.emit_signal("refresh")
+    tt:show()
+    awesome.emit_signal("refresh")
+    tt.wibox.x = x_offset
+    x_offset = x_offset + 640/5
+end
+
+mouse.coords{x=125, y= 0}
+-- mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/mode.lua

@@ -0,0 +1,23 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 200, height = 100}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+mouse.coords{x=50, y= 10}
+
+    local wb = wibox {width = 100, height = 44, x = 50, y = 25, visible = true}
+
+awesome.emit_signal("refresh")
+local tt = awful.tooltip {
+    text = "A tooltip!",
+    objects = {wb},
+}
+tt.bg = beautiful.bg_normal
+
+mouse.coords{x=75, y= 35}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/mode2.lua

@@ -0,0 +1,24 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 200, height = 100}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+mouse.coords{x=50, y= 10}
+
+    local wb = wibox {width = 100, height = 44, x = 50, y = 25, visible = true}
+
+awesome.emit_signal("refresh")
+local tt = awful.tooltip {
+    text = "A tooltip!",
+    objects = {wb},
+    mode = "outside",
+}
+tt.bg = beautiful.bg_normal
+
+mouse.coords{x=75, y= 35}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/mouse.lua

@@ -0,0 +1,20 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+screen[1]._resize {width = 200, height = 50} --DOC_HIDE
+screen.no_outline = true --DOC_HIDE
+local awful = {tooltip = require("awful.tooltip")} --DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+mouse.coords{x=50, y= 10} --DOC_HIDE
+mouse.push_history() --DOC_HIDE
+
+    local tt = awful.tooltip {
+        text = "A tooltip!",
+        visible = true,
+    }
+
+--DOC_NEWLINE
+
+    tt.bg = beautiful.bg_normal
+
+--DOC_NEWLINE

tests/examples/awful/tooltip/preferred_alignment.lua

@@ -0,0 +1,29 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 300, height = 150}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+-- mouse.coords{x=50, y= 10}
+
+    local wb = wibox {width = 100, height = 44, x = 100, y = 50, visible = true}
+
+awesome.emit_signal("refresh")
+
+for _, side in ipairs{ "left", "right", "bottom", "top" } do
+    local tt = awful.tooltip {
+        text = side,
+        objects = {wb},
+        mode = "outside",
+        preferred_positions = {side},
+        preferred_alignments = {"front"},
+    }
+    tt.bg = beautiful.bg_normal
+end
+
+mouse.coords{x=125, y= 75}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/preferred_alignment2.lua

@@ -0,0 +1,29 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 300, height = 150}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+-- mouse.coords{x=50, y= 10}
+
+    local wb = wibox {width = 100, height = 44, x = 100, y = 50, visible = true}
+
+awesome.emit_signal("refresh")
+
+for _, side in ipairs{ "left", "right", "bottom", "top" } do
+    local tt = awful.tooltip {
+        text = side,
+        objects = {wb},
+        mode = "outside",
+        preferred_positions = {side},
+        preferred_alignments = {"middle"},
+    }
+    tt.bg = beautiful.bg_normal
+end
+
+mouse.coords{x=125, y= 75}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/preferred_alignment3.lua

@@ -0,0 +1,29 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 300, height = 150}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+-- mouse.coords{x=50, y= 10}
+
+    local wb = wibox {width = 100, height = 44, x = 100, y = 50, visible = true}
+
+awesome.emit_signal("refresh")
+
+for _, side in ipairs{ "left", "right", "bottom", "top" } do
+    local tt = awful.tooltip {
+        text = side,
+        objects = {wb},
+        mode = "outside",
+        preferred_positions = {side},
+        preferred_alignments = {"back"},
+    }
+    tt.bg = beautiful.bg_normal
+end
+
+mouse.coords{x=125, y= 75}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/preferred_positions.lua

@@ -0,0 +1,28 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 300, height = 150}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+
+-- mouse.coords{x=50, y= 10}
+
+    local wb = wibox {width = 100, height = 44, x = 100, y = 50, visible = true}
+
+awesome.emit_signal("refresh")
+
+for _, side in ipairs{ "left", "right", "bottom", "top" } do
+    local tt = awful.tooltip {
+        text = side,
+        objects = {wb},
+        mode = "outside",
+        preferred_positions = {side},
+    }
+    tt.bg = beautiful.bg_normal
+end
+
+mouse.coords{x=125, y= 75}
+mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/shape.lua

@@ -0,0 +1,34 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+--DOC_HIDE_ALL
+screen[1]._resize {width = 640, height = 55}
+screen.no_outline = true
+local awful = {tooltip = require("awful.tooltip")}
+local beautiful = require("beautiful")
+local gears = {shape = require("gears.shape")}
+
+-- mouse.coords{x=50, y= 10}
+
+awesome.emit_signal("refresh")
+
+local x_offset = 0
+
+for _, shape in ipairs{ "rounded_rect", "rounded_bar", "octogon", "infobubble"} do
+    local tt = awful.tooltip {
+        text = shape,
+        mode = "mouse",
+        border_width = 2,
+        shape = gears.shape[shape],
+        border_color = beautiful.border_color,
+    }
+    tt.bg = beautiful.bg_normal
+    awesome.emit_signal("refresh")
+    tt:show()
+    awesome.emit_signal("refresh")
+    tt.wibox.x = x_offset
+    x_offset = x_offset + 640/5
+end
+
+mouse.coords{x=125, y= 0}
+-- mouse.push_history()
+awesome.emit_signal("refresh")

tests/examples/awful/tooltip/textclock.lua

@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+screen[1]._resize {width = 300, height = 75} --DOC_HIDE
+local awful = {tooltip = require("awful.tooltip"), wibar = require("awful.wibar")} --DOC_HIDE
+local wibox = { widget = { textclock = require("wibox.widget.textclock") }, --DOC_HIDE
+    layout = { align = require("wibox.layout.align") } } --DOC_HIDE
+
+    local mytextclock = wibox.widget.textclock()
+
+--DOC_NEWLINE
+
+local wb = awful.wibar { position = "top" } --DOC_HIDE
+
+wb:setup { layout = wibox.layout.align.horizontal, --DOC_HIDE
+    nil, nil, mytextclock} --DOC_HIDE
+
+awesome.emit_signal("refresh") --DOC_HIDE the hierarchy is async
+
+    local myclock_t = awful.tooltip {
+        objects        = { mytextclock },
+        timer_function = function()
+            return os.date("Today is %A %B %d %Y\nThe time is %T")
+        end,
+    }
+
+awesome.emit_signal("refresh") --DOC_HIDE
+
+mouse.coords{x=250, y= 10} --DOC_HIDE
+mouse.push_history() --DOC_HIDE
+
+assert(myclock_t.wibox and myclock_t.wibox.visible) --DOC_HIDE

tests/examples/awful/tooltip/textclock2.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+screen[1]._resize {width = 300, height = 75} --DOC_HIDE
+local awful = {tooltip = require("awful.tooltip"), wibar = require("awful.wibar")} --DOC_HIDE
+local wibox = { widget = { textclock = require("wibox.widget.textclock") }, --DOC_HIDE
+    layout = { align = require("wibox.layout.align") } } --DOC_HIDE
+
+    local mytextclock = wibox.widget.textclock()
+
+--DOC_NEWLINE
+
+local wb = awful.wibar { position = "top" } --DOC_HIDE
+
+wb:setup { layout = wibox.layout.align.horizontal, --DOC_HIDE
+    nil, nil, mytextclock} --DOC_HIDE
+
+awesome.emit_signal("refresh") --DOC_HIDE the hierarchy is async
+
+    local myclock_t = awful.tooltip { }
+--DOC_NEWLINE
+    myclock_t:add_to_object(mytextclock)
+--DOC_NEWLINE
+    mytextclock:connect_signal("mouse::enter", function()
+        myclock_t.text = os.date("Today is %A %B %d %Y\nThe time is %T")
+    end)
+
+awesome.emit_signal("refresh") --DOC_HIDE
+
+mouse.coords{x=250, y= 10} --DOC_HIDE
+mouse.push_history() --DOC_HIDE
+
+assert(myclock_t.wibox and myclock_t.wibox.visible) --DOC_HIDE

tests/examples/shims/awesome.lua

@@ -63,6 +63,9 @@ end
 -- Always show deprecated messages
 awesome.version = "v9999"
 
+-- SVG are composited. Without it we need a root surface
+awesome.composite_manager_running = true
+
 return awesome
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/shims/drawin.lua

@@ -2,6 +2,7 @@ local gears_obj = require("gears.object")
 
 local drawin, meta = awesome._shim_fake_class()
 local drawins = setmetatable({}, {__mode="v"})
+local cairo = require("lgi").cairo
 
 local function new_drawin(_, args)
     local ret = gears_obj()
@@ -30,6 +31,11 @@ local function new_drawin(_, args)
         }
     end
 
+    ret.data.drawable.valid    = true
+    ret.data.drawable.surface  = cairo.ImageSurface(cairo.Format.ARGB32, 0, 0)
+    ret.data.drawable.geometry = ret.geometry
+    ret.data.drawable.refresh  = function() end
+
     for _, k in pairs{ "buttons", "struts", "get_xproperty", "set_xproperty" } do
         ret[k] = function() end
     end

tests/examples/shims/mouse.lua

@@ -7,10 +7,34 @@ local mouse = {
     history       = {},
 }
 
+-- Avoid gears when possible
+local function contains(rect, point)
+    return point.x >= rect.x and point.x < rect.x+rect.width and
+        point.y >= rect.y and point.y < rect.y+rect.height
+end
+
 function mouse.coords(args)
     if args then
+        local old = {x = coords.x, y = coords.y}
         coords.x, coords.y = args.x, args.y
         table.insert(mouse.history, {x=coords.x, y=coords.y})
+
+        for _, d in ipairs(drawin.get()) do
+            local geo = d.geometry()
+            local was_in, is_in = contains(geo, old), contains(geo, coords)
+            local sig = {(is_in and not was_in) and "mouse::enter" or
+                (was_in and not is_in) and "mouse::leave" or "mouse::move"}
+
+            -- Enter is also a move, otherwise drawable.handle_motion isn't called
+            if sig[1] == "mouse::enter" then
+                table.insert(sig, "mouse::move")
+            end
+
+            for _, s in ipairs(sig) do
+                d:emit_signal(s, coords.x - geo.x, coords.y - geo.y)
+                d.drawable:emit_signal(s, coords.x - geo.x, coords.y - geo.y)
+            end
+        end
     end
 
     return coords