naughty: simplify notify and preset parameters

This makes all parameters available to notify() to be available in
preset table (and vice versa) and simplifies value selection.

Adds new config option: config.default_preset.

Also cleans up some comment redundancy.

Signed-off-by: koniu <gkusnierz@gmail.com>

lib/naughty.lua.in

@@ -10,7 +10,6 @@ local table = table
 local wibox = wibox
 local image = image
 local type = type
-local tostring = tostring
 local hooks = require("awful.hooks")
 local string = string
 local widget = widget
@@ -25,36 +24,27 @@ local dbus = dbus
 --- Notification library
 module("naughty")
 
---- Naughty configuration - a table containing common/default popup settings.
+--- Naughty configuration - a table containing common popup settings.
--- You can override some of these for individual popups using args to notify().
 -- @name config
--- @field screen Screen on which the popups will appear number. Default: 1
--- @field position Corner of the workarea the popups will appear.
---   Valid values: 'top_right', 'top_left', 'bottom_right', 'bottom_left'.
---   Default: 'top_right'
 -- @field padding Space between popups and edge of the workarea. Default: 4
--- @field width Width of a popup. Default: 300
 -- @field spacing Spacing between popups. Default: 1
--- @field ontop Boolean forcing popups to display on top. Default: true
--- @field margin Space between popup edge and content. Default: 10
 -- @field icon_dirs List of directories that will be checked by getIcon()
 --   Default: { "/usr/share/pixmaps/", }
 -- @field icon_formats List of formats that will be checked by getIcon()
 --   Default: { "png", "gif" }
--- @field border_width Border width. Default: 1
+-- @field default_preset Preset to be used by default.
+--   Default: config.presets.normal
 -- @class table
 
 config = {}
 config.padding = 4
 config.spacing = 1
-config.margin = 10
-config.ontop = true
 config.icon_dirs = { "/usr/share/pixmaps/", }
 config.icon_formats = { "png", "gif" }
 
-config.border_width = 1
 
 --- Notification Presets - a table containing presets for different purposes
+-- Preset is a table of any parameters available to notify()
 -- You have to pass a reference of a preset in your notify() call to use the preset
 -- At least the default preset named "normal" has to be defined
 -- The presets "low", "normal" and "critical" are used for notifications over DBUS
@@ -64,46 +54,20 @@ config.border_width = 1
 -- @field critical The preset for notifications with a critical urgency level
 -- @class table
 
---- Default preset for notifications
--- @name config.presets.normal
--- @field timeout Number of seconds after which popups disappear.
---   Set to 0 for no timeout. Default: 5
--- @field hover_timeout Delay in seconds after which hovered popup disappears.
---   Default: nil
--- @field border_color Border color.
---   Default:  beautiful.border_focus or '#535d6c'
--- @field fg Foreground color. Default: beautiful.fg_focus or '#ffffff'
--- @field bg Background color. Default: beautiful.bg_focus or '#535d6c'
--- @field font Popup font. Default: beautiful.font or "Verdana 8"
--- @field height Height of a single line of text. Default: 16
--- @field icon Popup icon. Default: nil
--- @field icon_size Size of the icon in pixels. Default: nil
--- @field callback function that will be called with all arguments
---  the notification will only be displayed if the function returns true
---  note: this function is only relevant to notifications sent via dbus
-
 config.presets = {
+    normal = {},
     low = {
         timeout = 5
     },
-    normal = {
-        timeout = 8,
-        hover_timeout = nil,
-        position = "top_right",
-        screen = 1,
-        width = nil,
-        height = nil,
-        icon = nil,
-        icon_size = nil
-    },
     critical = {
         bg = "#ff0000",
         fg = "#ffffff",
         timeout = 0,
-        height = 25
     }
 }
 
+config.default_preset = config.presets.normal
+
 -- DBUS Notification constants
 urgency = {
     low = "\0",
@@ -135,7 +99,7 @@ local counter = 1
 -- @field width Popup width
 -- @field die Function to be executed on timeout
 -- @field id Unique notification id based on a counter
--- @name notifications[position]
+-- @name notifications[screen][position]
 -- @class table
 
 notifications = {}
@@ -247,42 +211,60 @@ local function getIcon(name)
     end
 end
 
---- Create notification. args is a dictionary of optional arguments. For more information and defaults see respective fields in config table.
+--- Create notification. args is a dictionary of (optional) arguments.
--- @param text Text of the notification
+-- @param text Text of the notification. Default: ''
--- @param timeout Time in seconds after which popup expires
+-- @param title Title of the notification. Default: nil
--- @param title Title of the notification
+-- @param timeout Time in seconds after which popup expires.
--- @param position Corner of the workarea the popups will appear
+--   Set 0 for no timeout. Default: 5
--- @param icon Path to icon
+-- @param hover_timeout Delay in seconds after which hovered popup disappears.
--- @param icon_size Desired icon size in px
+--   Default: nil
--- @param fg Foreground color
+-- @param screen Target screen for the notification. Default: 1
--- @param bg Background color
+-- @param position Corner of the workarea displaying the popups.
--- @param screen Target screen for the notification
+--   Values: "top_right" (default), "top_left", "bottom_left", "bottom_right".
--- @param ontop Target screen for the notification
+-- @param ontop Boolean forcing popups to display on top. Default: true
--- @param run Function to run on left click
+-- @param height Popup height. Default: nil (auto)
--- @param width The popup width
+-- @param width Popup width. Default: nil (auto)
--- @field hover_timeout Delay in seconds after which hovered popup disappears.
+-- @param font Notification font. Default: beautiful.font or awesome.font
+-- @param icon Path to icon. Default: nil
+-- @param icon_size Desired icon size in px. Default: nil
+-- @param fg Foreground color. Default: beautiful.fg_focus or '#ffffff'
+-- @param bg Background color. Default: beautiful.bg_focus or '#535d6c'
+-- @param border_width Border width. Default: 1
+-- @param border_color Border color.
+--   Default: beautiful.border_focus or '#535d6c'
+-- @param run Function to run on left click. Default: nil
+-- @param preset Table with any of the above parameters. Note: Any parameters
+--   specified directly in args will override ones defined in the preset.
 -- @param replaces_id Replace the notification with the given ID
--- @usage naughty.notify({ title = 'Achtung!', text = 'You\'re idling', timeout = 0 })
+-- @param callback function that will be called with all arguments
+--  the notification will only be displayed if the function returns true
+--  note: this function is only relevant to notifications sent via dbus
+-- @usage naughty.notify({ title = "Achtung!", text = "You're idling", timeout = 0 })
 -- @return The notification object
 function notify(args)
     -- gather variables together
-    local timeout = args.timeout or (args.preset and args.preset.timeout) or config.presets.normal.timeout
+    local preset = args.preset or config.default_preset or {}
-    local icon = args.icon or (args.preset and args.preset.icon) or config.icon
+    local timeout = args.timeout or preset.timeout or 5
-    local icon_size = args.icon_size or (args.preset and args.preset.icon_size) or config.icon_size
+    local icon = args.icon or preset.icon
-    local text = tostring(args.text) or ""
+    local icon_size = args.icon_size or preset.icon_size
-    local screen = args.screen or (args.preset and args.preset.screen) or config.presets.normal.screen
+    local text = args.text or preset.text or ""
-    local ontop = args.ontop or config.ontop
+    local title = args.title or preset.title
-    local width = args.width or (args.preset and args.preset.width) or config.presets.normal.width
+    local screen = args.screen or preset.screen or 1
-    local height = args.preset and args.preset.height or config.presets.normal.height
+    local ontop = args.ontop or preset.ontop or true
-    local hover_timeout = args.hover_timeout or (args.preset and args.preset.hover_timeout) or config.presets.normal.hover_timeout
+    local width = args.width or preset.width
-    local opacity = args.opacity or (args.preset and args.preset.opacity) or config.presets.normal.opacity
+    local height = args.height or preset.height
+    local hover_timeout = args.hover_timeout or preset.hover_timeout
+    local opacity = args.opacity or preset.opacity
+    local margin = args.margin or preset.margin or "5"
+    local border_width = args.border_width or preset.border_width or "1"
+    local position = args.position or preset.position or "top_right"
 
     -- beautiful
     local beautiful = bt.get()
-    local font = args.font or config.font or (args.preset and args.preset.font) or config.presets.normal.font or beautiful.font or "Verdana 8"
+    local font = args.font or preset.font or beautiful.font or awesome.font
-    local fg = args.fg or config.fg or (args.preset and args.preset.fg) or config.presets.normal.fg or beautiful.fg_normal or '#ffffff'
+    local fg = args.fg or preset.fg or beautiful.fg_normal or '#ffffff'
-    local bg = args.bg or config.bg or (args.preset and args.preset.bg) or config.presets.normal.bg or beautiful.bg_normal or '#535d6c'
+    local bg = args.bg or preset.bg or beautiful.bg_normal or '#535d6c'
-    local border_color = (args.preset and args.preset.border_color) or config.presets.normal.border_color or beautiful.bg_focus or '#535d6c'
+    local border_color = args.border_color or preset.border_color or beautiful.bg_focus or '#535d6c'
     local notification = {}
 
     -- replace notification if needed
@@ -305,10 +287,9 @@ function notify(args)
         notification.id = counter
     end
 
-    notification.position = args.position or (args.preset and args.preset.position) or config.presets.normal.position
+    notification.position = position
 
-    local title = ""
+    if title then title = title .. "\n" else title = "" end
-    if args.title then title = tostring(args.title) .. "\n"  end
 
     -- hook destroy
     local die = function () destroy(notification) end
@@ -331,7 +312,7 @@ function notify(args)
     -- create textbox
     local textbox = widget({ type = "textbox", align = "flex" })
     textbox:buttons(util.table.join(button({ }, 1, run), button({ }, 3, die)))
-    textbox:margin({ right = config.margin, left = config.margin, bottom = 2 * config.margin })
+    textbox:margin({ right = margin, left = margin, bottom = 2 * margin })
     textbox.text = string.format('<span font_desc="%s"><b>%s</b>%s</span>', font, title, text)
     if hover_timeout then textbox.mouse_enter = hover_destroy end
 
@@ -367,8 +348,8 @@ function notify(args)
     notification.box = wibox({ position = "floating",
                                fg = fg,
                                bg = bg,
-                               border_color = args.preset and args.preset.border_color or config.presets.normal.border_color,
+                               border_color = border_color,
-                               border_width = config.border_width })
+                               border_width = border_width })
 
     -- position the wibox
     if height then
@@ -387,13 +368,13 @@ function notify(args)
     if width then
         notification.width = width
     else
-        notification.width = textbox:extents().width + (iconbox and iconbox:extents().width or 0) + (2 * (config.border_width or 0))
+        notification.width = textbox:extents().width + (iconbox and iconbox:extents().width or 0) + (2 * (border_width or 0))
     end
-    if notification.width > capi.screen[screen].workarea.width - 2 * (config.border_width or 0) then
+    if notification.width > capi.screen[screen].workarea.width - 2 * (border_width or 0) then
-        notification.width = capi.screen[screen].workarea.width - 2 * (config.border_width or 0)
+        notification.width = capi.screen[screen].workarea.width - 2 * (border_width or 0)
     end
-    if notification.height > capi.screen[screen].workarea.height - 2 * (config.border_width or 0) - 2 * (config.padding or 0) then
+    if notification.height > capi.screen[screen].workarea.height - 2 * (border_width or 0) - 2 * (config.padding or 0) then
-        notification.height = capi.screen[screen].workarea.height - 2 * (config.border_width or 0) - 2 * (config.padding or 0)
+        notification.height = capi.screen[screen].workarea.height - 2 * (border_width or 0) - 2 * (config.padding or 0)
     end
 
     local offset = get_offset(screen, notification.position, nil, notification.width, notification.height)