API consistency

docs/widgets.rst

@@ -28,8 +28,9 @@ Creates a button widget at position ``(x,y)`` with width ``w`` and height
 
 Creates a label at position ``(x,y)`` with width ``w`` and height ``h``.
 
-.. function:: ImageButton(options, x,y)
+.. function:: ImageButton(normal, options, x,y)
 
+   :param Image notmal: Image of the button in normal state.
    :param table options: Widget options.
    :param numbers x,y: Upper left corner of the widget.
    :returns: Return state (see below).
@@ -37,9 +38,10 @@ Creates a label at position ``(x,y)`` with width ``w`` and height ``h``.
 Creates an image button widget at position ``(x,y)``.
 Unlike all other widgets, an ``ImageButton`` is not affected by the current
 theme.
-The options table must at least contain an image for the ``normal`` state.
-The pixels with non-zero alpha value define the active area of the widget.
-You can provide additional ``hot`` and ``active`` images, but the widget area
+The argument ``normal`` defines the image of the normal state as well as the
+area of the widget: The button activates when the mouse is over a pixel with
+non-zero alpha value.
+You can provide additional ``hover`` and ``active`` images, but the widget area
 is always computed from the ``normal`` image.
 
 Note that ``ImageButton`` does not recieve width and height parameters. As
@@ -48,13 +50,13 @@ such, it does not necessarily honor the cell size of a :doc:`layout`.
 **Additional Options:**
 
 ``normal``
-   Image for the normal state of the widget. Mandatory.
+   Image for the normal state of the widget. Defaults to widget payload.
 
-``hot``
+``hover``
    Image for the hot state of the widget. Defaults to ``normal`` if omitted.
 
 ``active``
-   Image for the active state of the widget. Defaults to ``
+   Image for the active state of the widget. Defaults to ``hover`` if omitted.
 
 Mutable Widgets
 ---------------

imagebutton.lua

@@ -3,11 +3,11 @@
 local BASE = (...):match('(.-)[^%.]+$')
 local core = require(BASE .. 'core')
 
-return function(...)
+return function(normal, ...)
 	local opt, x,y = core.getOptionsAndSize(...)
-	opt.normal = opt.normal or opt[1]
-	opt.hot = opt.hot or opt[2] or opt.normal
-	opt.active = opt.active or opt[3] or opt.hot
+	opt.normal = normal or opt.normal or opt[1]
+	opt.hover = opt.hover or opt[2] or opt.normal
+	opt.active = opt.active or opt[3] or opt.hover
 	assert(opt.normal, "Need at least `normal' state image")
 	opt.id = opt.id or opt.normal
 
@@ -23,10 +23,10 @@ return function(...)
 	end)
 
 	local img = opt.normal
-	if core.isHot(opt.id) then
-		img = opt.hot
-	elseif core.isActive(opt.id) then
+	if core.isActive(opt.id) then
 		img = opt.active
+	elseif core.isHot(opt.id) then
+		img = opt.hover
 	end
 
 	core.registerDraw(love.graphics.setColor, 255,255,255)
@@ -35,7 +35,7 @@ return function(...)
 	return {
 		id = opt.id,
 		hit = core.mouseReleasedOn(opt.id),
-		hovered = core.isHot(opt.id),
+		hover = core.isHot(opt.id),
 		entered = core.isHot(opt.id) and not core.wasHot(opt.id),
 		left = not core.isHot(opt.id) and core.wasHot(opt.id)
 	}