Merge pull request #377 from blueyed/naughty-focused-screen

Naughty: default to focused screen

lib/naughty/core.lua

@@ -18,6 +18,7 @@ local capi = { screen = screen,
                awesome = awesome }
 local timer = require("gears.timer")
 local button = require("awful.button")
+local screen = require("awful.screen")
 local util = require("awful.util")
 local bt = require("beautiful")
 local wibox = require("wibox")
@@ -35,45 +36,24 @@ local naughty = {}
 Naughty configuration - a table containing common popup settings.
 
 @table naughty.config
-@field padding Space between popups and edge of the workarea.
+@tfield[opt=4] int padding Space between popups and edge of the workarea.
-   Default: `4`
+@tfield[opt=1] int spacing Spacing between popups.
-@field spacing Spacing between popups.
+@tfield[opt={"/usr/share/pixmaps/"}] table icon_dirs List of directories
-   Default: `1`
+  that will be checked by `getIcon()`.
-@field icon_dirs List of directories that will be checked by `getIcon()`.
+@tfield[opt={ "png", "gif" }] table icon_formats List of formats that will be
-   Default: `{ "/usr/share/pixmaps/", }`
+  checked by `getIcon()`.
-@field icon_formats List of formats that will be checked by `getIcon()`.
+@tfield[opt] function notify_callback Callback used to modify or reject
-   Default: `{ "png", "gif" }`
+notifications, e.g.
-@field notify_callback Callback used to modify or reject notifications.
-   Default: `nil`
     naughty.config.notify_callback = function(args)
         args.text = 'prefix: ' .. args.text
         return args
     end
 
-@field presets Notification Presets - a table containing presets for
+@tfield table presets Notification presets.  See `config.presets`.
-   different purposes.  Preset is a table of any parameters available to
-   `notify()`, overriding default values (`naughty.config.defaults`) You have
-   to pass a reference of a preset in your notify() call to use the preset The
-   presets `"low"`, `"normal"` and `"critical"` are used for notifications
-   over DBUS.
 
-@field presets.low The preset for notifications with low urgency level.
+@tfield table defaults Default values for the params to `notify()`.  These can
-@field presets.normal The default preset for every notification without a
+  optionally be overridden by specifying a preset.  See `config.defaults`.
-   preset that will also be used for normal urgency level.
-@field presets.critical The preset for notifications with a critical urgency
-   level.
 
-@field defaults Default values for the params to `notify()`.
-   These can optionally be overridden by specifying a preset.
-
-@field mapping DBUS notification to preset mapping.
-   The first element is an object containing the filter If the rules in the
-   filter matches the associated preset will be applied The rules object can
-   contain: urgency, category, appname The second element is the preset
-
-@field mapping.1 low urgency
-@field mapping.2 normal urgency
-@field mapping.3 critical urgency
 --]]
 --
 naughty.config = {
@@ -84,6 +64,27 @@ naughty.config = {
     notify_callback = nil,
 }
 
+--- Notification presets for `naughty.notify`.
+-- This holds presets for different purposes.  A preset is a table of any
+-- parameters for `notify()`, overriding the default values
+-- (`naughty.config.defaults`).
+--
+-- You have to pass a reference of a preset in your `notify()` as the `preset`
+-- argument.
+--
+-- The presets `"low"`, `"normal"` and `"critical"` are used for notifications
+-- over DBUS.
+--
+-- @table config.presets
+-- @tfield table low The preset for notifications with low urgency level.
+-- @tfield[opt=5] int low.timeout
+-- @tfield[opt=empty] table normal The default preset for every notification without a
+--   preset that will also be used for normal urgency level.
+-- @tfield table critical The preset for notifications with a critical urgency
+--   level.
+-- @tfield[opt="#ff0000"] string critical.bg
+-- @tfield[opt="#ffffff"] string critical.fg
+-- @tfield[opt=0] string critical.timeout
 naughty.config.presets = {
     low = {
         timeout = 5
@@ -96,13 +97,23 @@ naughty.config.presets = {
     }
 }
 
+--- Defaults for `naughty.notify`.
+--
+-- @table config.defaults
+-- @tfield[opt=5] int timeout
+-- @tfield[opt=""] string text
+-- @tfield[opt] int screen Defaults to `awful.screen.focused`.
+-- @tfield[opt=true] boolean ontop
+-- @tfield[opt=5] int margin
+-- @tfield[opt=1] int border_width
+-- @tfield[opt="top_right"] string position
 naughty.config.defaults = {
     timeout = 5,
     text = "",
-    screen = 1,
+    screen = nil,
     ontop = true,
-    margin = "5",
+    margin = 5,
-    border_width = "1",
+    border_width = 1,
     position = "top_right"
 }
 
@@ -375,52 +386,35 @@ end
 --- Create a notification.
 --
 -- @tab args The argument table containing any of the arguments below.
--- @string args.text Text of the notification.
+-- @string[opt=""] args.text Text of the notification.
---   Default: ''
+-- @string[opt] args.title Title of the notification.
--- @string args.title Title of the notification.
+-- @int[opt=5] args.timeout Time in seconds after which popup expires.
---   Default: nil
--- @int args.timeout Time in seconds after which popup expires.
 --   Set 0 for no timeout.
---   Default: 5
+-- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears.
--- @int args.hover_timeout Delay in seconds after which hovered popup disappears.
+-- @int[opt=focused] args.screen Target screen for the notification.
---   Default: nil
+-- @string[opt="top_right"] args.position Corner of the workarea displaying the popups.
--- @int args.screen Target screen for the notification.
+--   Values: `"top_right"`, `"top_left"`, `"bottom_left"`,
---   Default: 1
--- @string args.position Corner of the workarea displaying the popups.
---   Values: `"top_right"` (default), `"top_left"`, `"bottom_left"`,
 --   `"bottom_right"`, `"top_middle"`, `"bottom_middle"`.
--- @bool args.ontop Boolean forcing popups to display on top.
+-- @bool[opt=true] args.ontop Boolean forcing popups to display on top.
---   Default: true
+-- @int[opt=auto] args.height Popup height.
--- @int args.height Popup height.
+-- @int[opt=auto] args.width Popup width.
---   Default: nil (auto)
+-- @string[opt=beautiful.font or awesome.font] args.font Notification font.
--- @int args.width Popup width.
+-- @string[opt] args.icon Path to icon.
---   Default: nil (auto)
+-- @int[opt] args.icon_size Desired icon size in px.
--- @string args.font Notification font.
+-- @string[opt=`beautiful.fg_focus` or `'#ffffff'`] args.fg Foreground color.
---   Default: beautiful.font or awesome.font
+-- @string[opt=`beautiful.bg_focus` or `'#535d6c'`] args.bg Background color.
--- @string args.icon Path to icon.
+-- @int[opt=1] args.border_width Border width.
---   Default: nil
+-- @string[opt=`beautiful.border_focus` or `'#535d6c'`] args.border_color Border color.
--- @int args.icon_size Desired icon size in px.
+-- @tparam[opt] func args.run Function to run on left click.
---   Default: nil
+-- @tparam[opt] func args.destroy Function to run when notification is destroyed.
--- @string args.fg Foreground color.
+-- @tparam[opt] table args.preset Table with any of the above parameters.
---   Default: `beautiful.fg_focus` or `'#ffffff'`
+--   Note: Any parameters specified directly in args will override ones defined
--- @string args.bg Background color.
+--   in the preset.
---   Default: `beautiful.bg_focus` or `'#535d6c'`
+-- @tparam[opt] int args.replaces_id Replace the notification with the given ID.
--- @int args.border_width Border width.
+-- @tparam[opt] func args.callback Function that will be called with all arguments.
---   Default: 1
+--   The notification will only be displayed if the function returns true.
--- @string args.border_color Border color.
+--   Note: this function is only relevant to notifications sent via dbus.
---   Default: `beautiful.border_focus` or `'#535d6c'`
+-- @tparam[opt] table args.actions Mapping that maps a string to a callback when this
--- @tparam func args.run Function to run on left click. Default: nil
--- @tparam func args.destroy Function to run when notification is destroyed. Default: nil.
--- @tparam table args.preset Table with any of the above parameters.
---                          Note: Any parameters specified directly in args
---                          will override ones defined in the preset.
--- @tparam int args.replaces_id Replace the notification with the given ID.
--- @tparam func args.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.
--- @tparam table args.actions Mapping that maps a string to a callback when this
 --   action is selected.
 -- @usage naughty.notify({ title = "Achtung!", text = "You're idling", timeout = 0 })
 -- @return The notification object
@@ -438,7 +432,7 @@ function naughty.notify(args)
     local icon_size = args.icon_size or preset.icon_size
     local text = args.text or preset.text
     local title = args.title or preset.title
-    local screen = args.screen or preset.screen
+    local screen = args.screen or preset.screen or screen.focused()
     local ontop = args.ontop or preset.ontop
     local width = args.width or preset.width
     local height = args.height or preset.height

lib/naughty/dbus.lua

@@ -36,12 +36,15 @@ local urgency = {
     critical = "\2"
 }
 
---- DBUS notification to preset mapping
+--- DBUS notification to preset mapping.
--- The first element is an object containing the filter
+-- The first element is an object containing the filter.
--- If the rules in the filter matches the associated preset will be applied
+-- If the rules in the filter match, the associated preset will be applied.
--- The rules object can contain: urgency, category, appname
+-- The rules object can contain the following keys: urgency, category, appname.
--- The second element is the preset
+-- The second element is the preset.
-
+-- @tfield table 1 low urgency
+-- @tfield table 2 normal urgency
+-- @tfield table 3 critical urgency
+-- @table config.mapping
 dbus.config.mapping = {
     {{urgency = urgency.low}, naughty.config.presets.low},
     {{urgency = urgency.normal}, naughty.config.presets.normal},