From 4b94f05799be8d59b84eadb3036020c68f97cc08 Mon Sep 17 00:00:00 2001 From: "Ignas Anikevicius (gns_ank)" Date: Sun, 25 May 2014 13:25:01 +0100 Subject: [PATCH] Docs: Naughty - mostly done Reorganise the config table, so that we have a single table and the fields are nested. Signed-off-by: Ignas Anikevicius (gns_ank) --- lib/naughty/core.lua.in | 144 +++++++++++++++++++++++----------------- 1 file changed, 82 insertions(+), 62 deletions(-) diff --git a/lib/naughty/core.lua.in b/lib/naughty/core.lua.in index e1de518c..8d7a84a1 100644 --- a/lib/naughty/core.lua.in +++ b/lib/naughty/core.lua.in @@ -32,44 +32,56 @@ local tins = table.insert local naughty = {} --- Naughty configuration - a table containing common popup settings. --- @table naughty.config -naughty.config = {} ---- Space between popups and edge of the workarea. --- Default: 4 --- @table naughty.config.padding -naughty.config.padding = 4 ---- Spacing between popups. Default: `1` --- @table naughty.config.spacing -naughty.config.spacing = 1 ---- List of directories that will be checked by getIcon(). --- Default: `{ "/usr/share/pixmaps/", }` --- @table naughty.config.icon_dirs -naughty.config.icon_dirs = { "/usr/share/pixmaps/", } ---- List of formats that will be checked by getIcon(). --- Default: `{ "png", "gif" }` --- @table naughty.config.icon_formats -naughty.config.icon_formats = { "png", "gif" } ---- Callback used to modify or reject notifications. --- Default: `nil` --- @usage --- naughty.config.notify_callback = function(args) --- args.text = 'prefix: ' .. args.text --- return args --- end --- @table naughty.config.notify_callback -naughty.config.notify_callback = nil - - ---- Notification Presets - a table containing presets for 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 low The preset for notifications with low urgency level --- @field normal The default preset for every notification without a preset that will also be used for normal urgency level --- @field critical The preset for notifications with a critical urgency level --- @table naughty.config.presets +-- @table naughty.config +-- @field padding Space between popups and edge of the workarea. +-- Default: `4` +-- @field spacing Spacing between popups. +-- Default: `1` +-- @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 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 +-- 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. +-- @field presets.normal The default preset for every notification without a +-- 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 = { + padding = 4, + spacing = 1, + icon_dirs = { "/usr/share/pixmaps/", }, + icon_formats = { "png", "gif" }, + notify_callback = nil, +} + naughty.config.presets = { low = { timeout = 5 @@ -82,12 +94,6 @@ naughty.config.presets = { } } ---- Default values for the params to notify(). --- These can optionally be overridden by specifying a preset --- --- @see naughty.config.presets --- @see naughty.notify --- @table naughty.config.defaults naughty.config.defaults = { timeout = 5, text = "", @@ -260,28 +266,42 @@ function naughty.getById(id) end end ---- Create notification. args is a dictionary of (optional) arguments. --- @tparam table args The argument table containing any of the arguments bellow. --- @tparam string args.text Text of the notification. Default: '' --- @tparam string args.title Title of the notification. Default: nil --- @tparam int args.timeout Time in seconds after which popup expires. --- Set 0 for no timeout. Default: 5 --- @tparam int args.hover_timeout Delay in seconds after which hovered popup disappears. +--- Create notification. +-- +-- @tab args The argument table containing any of the arguments bellow. +-- @string args.text Text of the notification. +-- Default: '' +-- @string args.title Title of the notification. -- Default: nil --- @tparam int args.screen Target screen for the notification. Default: 1 --- @tparam string args.position Corner of the workarea displaying the popups. +-- @int args.timeout Time in seconds after which popup expires. +-- Set 0 for no timeout. +-- Default: 5 +-- @int args.hover_timeout Delay in seconds after which hovered popup disappears. +-- Default: nil +-- @int args.screen Target screen for the notification. +-- 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"`. --- @tparam bool args.ontop Boolean forcing popups to display on top. Default: true --- @tparam int args.height Popup height. Default: nil (auto) --- @tparam int args.width Popup width. Default: nil (auto) --- @tparam string args.font Notification font. Default: beautiful.font or awesome.font --- @tparam string args.icon Path to icon. Default: nil --- @tparam int args.icon_size Desired icon size in px. Default: nil --- @tparam string args.fg Foreground color. Default: `beautiful.fg_focus` or `'#ffffff'` --- @tparam string args.bg Background color. Default: `beautiful.bg_focus` or `'#535d6c'` --- @tparam int args.border_width Border width. Default: 1 --- @tparam string args.border_color Border color. +-- @bool args.ontop Boolean forcing popups to display on top. +-- Default: true +-- @int args.height Popup height. +-- Default: nil (auto) +-- @int args.width Popup width. +-- Default: nil (auto) +-- @string args.font Notification font. +-- Default: beautiful.font or awesome.font +-- @string args.icon Path to icon. +-- Default: nil +-- @int args.icon_size Desired icon size in px. +-- Default: nil +-- @string args.fg Foreground color. +-- Default: `beautiful.fg_focus` or `'#ffffff'` +-- @string args.bg Background color. +-- Default: `beautiful.bg_focus` or `'#535d6c'` +-- @int args.border_width Border width. +-- Default: 1 +-- @string args.border_color Border color. -- Default: `beautiful.border_focus` or `'#535d6c'` -- @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.