From e5ebcc1e4cb526c0b9d0d2dea5efc374a025f4df Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 29 Sep 2016 02:29:38 -0400 Subject: [PATCH 1/4] prompt: Allow each argument to be passed to the "args" This is the first step in deprecating them. A function with so many optional arguments is just bad design. The next few commits will rewrite the documentation and deprecate the old arguments. --- lib/awful/prompt.lua | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index c29291da..c16e435e 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -280,6 +280,17 @@ function prompt.run(args, textbox, exe_callback, completion_callback, local selectall = args.selectall local hooks = {} + -- This function has already an absurd number of parameters, allow them + -- to be set using the args to avoid a "nil, nil, nil, nil, foo" scenario + keypressed_callback = keypressed_callback or args.keypressed_callback + changed_callback = changed_callback or args.changed_callback + done_callback = done_callback or args.done_callback + history_max = history_max or args.history_max + history_path = history_path or args.history_path + completion_callback = completion_callback or args.completion_callback + exe_callback = exe_callback or args.exe_callback + textbox = textbox or args.textbox + search_term=nil history_check_load(history_path, history_max) From c00c14ade34d47dbeded7c4317136a88684128c4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 29 Sep 2016 02:36:13 -0400 Subject: [PATCH 2/4] doc: Improve the prompt documentation It was still pre-ldoc --- lib/awful/prompt.lua | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index c16e435e..6772b670 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -225,8 +225,29 @@ end -- history file. This does not delete new commands or history entries under -- user editing. -- --- @tparam table args A table with optional arguments: `fg_cursor`, `bg_cursor`, --- `ul_cursor`, `prompt`, `text`, `selectall`, `font`, `autoexec`, `hooks`. +-- @tparam[opt={}] table args A table with optional arguments +-- @tparam[opt] gears.color args.fg_cursor +-- @tparam[opt] gears.color args.bg_cursor +-- @tparam[opt] gears.color args.ul_cursor +-- @tparam[opt] widget args.prompt +-- @tparam[opt] string args.text +-- @tparam[opt] boolean args.selectall +-- @tparam[opt] string args.font +-- @tparam[opt] boolean args.autoexec +-- @tparam widget args.textbox The textbox to use for the prompt. +-- @tparam function args.exe_callback The callback function to call with command as argument +-- when finished. +-- @tparam function args.completion_callback The callback function to call to get completion. +-- @tparam[opt] string args.history_path File path where the history should be +-- saved, set nil to disable history +-- @tparam[opt] function args.history_max Set the maximum entries in history +-- file, 50 by default +-- @tparam[opt] function args.done_callback The callback function to always call +-- without arguments, regardless of whether the prompt was cancelled. +-- @tparam[opt] function args.changed_callback The callback function to call +-- with command as argument when a command was changed. +-- @tparam[opt] function args.keypressed_callback The callback function to call +-- with mod table, key and command as arguments when a key was pressed. -- @tparam[opt] table args.hooks The "hooks" argument uses a syntax similar to -- `awful.key`. It will call a function for the matching modifiers + key. -- It receives the command (widget text/input) as an argument. From 11644f4582e1e120ba06cce6defdb77af0063eef Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 29 Sep 2016 02:41:01 -0400 Subject: [PATCH 3/4] prompt: Deprecate 8 parameters. --- awesomerc.lua | 10 +++++---- lib/awful/prompt.lua | 53 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 54 insertions(+), 9 deletions(-) diff --git a/awesomerc.lua b/awesomerc.lua index b26f0a04..87d9da74 100755 --- a/awesomerc.lua +++ b/awesomerc.lua @@ -332,10 +332,12 @@ globalkeys = awful.util.table.join( awful.key({ modkey }, "x", function () - awful.prompt.run({ prompt = "Run Lua code: " }, - awful.screen.focused().mypromptbox.widget, - awful.util.eval, nil, - awful.util.get_cache_dir() .. "/history_eval") + awful.prompt.run { + prompt = "Run Lua code: ", + textbox = awful.screen.focused().mypromptbox.widget, + exe_callback = awful.util.eval, + history_path = awful.util.get_cache_dir() .. "/history_eval" + } end, {description = "lua execute prompt", group = "awesome"}), -- Menubar diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index 6772b670..3c49a56f 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -269,20 +269,23 @@ end -- return command -- end} -- } --- @param textbox The textbox to use for the prompt. +-- @param textbox The textbox to use for the prompt. [**DEPRECATED**] -- @param exe_callback The callback function to call with command as argument --- when finished. +-- when finished. [**DEPRECATED**] -- @param completion_callback The callback function to call to get completion. +-- [**DEPRECATED**] -- @param[opt] history_path File path where the history should be --- saved, set nil to disable history +-- saved, set nil to disable history [**DEPRECATED**] -- @param[opt] history_max Set the maximum entries in history --- file, 50 by default +-- file, 50 by default [**DEPRECATED**] -- @param[opt] done_callback The callback function to always call -- without arguments, regardless of whether the prompt was cancelled. +-- [**DEPRECATED**] -- @param[opt] changed_callback The callback function to call --- with command as argument when a command was changed. +-- with command as argument when a command was changed. [**DEPRECATED**] -- @param[opt] keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. +-- [**DEPRECATED**] function prompt.run(args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback, changed_callback, keypressed_callback) @@ -301,6 +304,46 @@ function prompt.run(args, textbox, exe_callback, completion_callback, local selectall = args.selectall local hooks = {} + -- A function with 9 parameters deserve to die + if textbox then + util.deprecate("Use args.textbox instead of the textbox parameter") + end + if exe_callback then + util.deprecate( + "Use args.exe_callback instead of the exe_callback parameter" + ) + end + if completion_callback then + util.deprecate( + "Use args.completion_callback instead of the completion_callback parameter" + ) + end + if history_path then + util.deprecate( + "Use args.history_path instead of the history_path parameter" + ) + end + if history_max then + util.deprecate( + "Use args.history_max instead of the history_max parameter" + ) + end + if done_callback then + util.deprecate( + "Use args.done_callback instead of the done_callback parameter" + ) + end + if changed_callback then + util.deprecate( + "Use args.changed_callback instead of the changed_callback parameter" + ) + end + if keypressed_callback then + util.deprecate( + "Use args.keypressed_callback instead of the keypressed_callback parameter" + ) + end + -- This function has already an absurd number of parameters, allow them -- to be set using the args to avoid a "nil, nil, nil, nil, foo" scenario keypressed_callback = keypressed_callback or args.keypressed_callback From ef50f75551b6f117bbc081b53130615f137a790e Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 29 Sep 2016 02:46:04 -0400 Subject: [PATCH 4/4] prompt: Add a key release callback. A possible use case is to highlight something when a key is pressed and un-highlight it when the key is released. --- lib/awful/prompt.lua | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index 3c49a56f..279d9248 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -248,6 +248,8 @@ end -- with command as argument when a command was changed. -- @tparam[opt] function args.keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. +-- @tparam[opt] function args.keyreleased_callback The callback function to call +-- with mod table, key and command as arguments when a key was pressed. -- @tparam[opt] table args.hooks The "hooks" argument uses a syntax similar to -- `awful.key`. It will call a function for the matching modifiers + key. -- It receives the command (widget text/input) as an argument. @@ -407,11 +409,18 @@ function prompt.run(args, textbox, exe_callback, completion_callback, grabber = keygrabber.run( function (modifiers, key, event) - if event ~= "press" then return end -- Convert index array to hash table local mod = {} for _, v in ipairs(modifiers) do mod[v] = true end + if event ~= "press" then + if args.keyreleased_callback then + args.keyreleased_callback(mod, key, command) + end + + return + end + -- Call the user specified callback. If it returns true as -- the first result then return from the function. Treat the -- second and third results as a new command and new prompt