feat: define scroll speed + smart_send to qflist (#610)

* smart send to qflist

* Previewer scrolling for half window height

* Start doing cleanup in readme

* feat: add ability to define the scrolling speed

* move scrolling action to action.set

* docs: added more docs for actions

* [docgen] Update doc/telescope.txt
skip-checks: true

Co-authored-by: Simon Hauser <Simon-Hauser@outlook.de>
Co-authored-by: Github Actions <actions@github>

README.md

@@ -398,7 +398,6 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.highlights`                | Lists all highlights.                                                                       |
 | `builtin.current_buffer_fuzzy_find` | Searches in current buffer lines.                                                           |
 | `builtin.current_buffer_tags`       | Lists Tags in current buffer.                                                               |
-| ..................................  | Your next awesome picker function here :D                                                   |
 
 ### LSP Pickers
 
@@ -411,7 +410,6 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.lsp_range_code_actions`    | Lists LSP range code action to be trigged on enter.                                         |
 | `builtin.lsp_document_diagnostics`  | Lists LSP Diagnostics in the current document.                                              |
 | `builtin.lsp_workspace_diagnostics` | Lists LSP Diagnostics in the workspace if supported and otherwise open buffers.             |
-| ..................................  | Your next awesome picker function here :D                                                   |
 
 ### Git Pickers
 
@@ -421,14 +419,12 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.git_bcommits`              | Lists buffer's git commits with diff preview and checkouts it out on enter.                 |
 | `builtin.git_branches`              | Lists all branches with log preview, checkout action (<cr>), track action (<c-t>) and rebase action(<c-r>). |
 | `builtin.git_status`                | Lists current changes per file with diff preview and add action. (Multiselection still WIP) |
-| ..................................  | Your next awesome picker function here :D                                                   |
 
 ### Treesitter Picker
 
 | Functions                           | Description                                                                                 |
 |-------------------------------------|---------------------------------------------------------------------------------------------|
 | `builtin.treesitter`                | Lists Function names, variables, from Treesitter!                                           |
-| ..................................  | Your next awesome picker function here :D                                                   |
 
 ### Lists Picker
 
@@ -438,19 +434,17 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.builtin`                   | Lists Built-in pickers and run them on enter.                                               |
 | `builtin.reloader`                  | Lists lua modules and reload them on enter.                                                 |
 | `builtin.symbols`                   | Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found [here](https://github.com/nvim-telescope/telescope-symbols.nvim) |
-| ..................................  | Your next awesome picker function here :D                                                   |
 
 ## Previewers
 
 | Previewers                         | Description                                                     |
 |------------------------------------|-----------------------------------------------------------------|
-| `previewers.vim_buffer_cat.new`    | Experimental previewer for files. Uses vim buffers              |
+| `previewers.vim_buffer_cat.new`    | Default previewer for files. Uses vim buffers                   |
-| `previewers.vim_buffer_vimgrep.new`| Experimental previewer for grep and similar. Uses vim buffers   |
+| `previewers.vim_buffer_vimgrep.new`| Default previewer for grep and similar. Uses vim buffers        |
-| `previewers.vim_buffer_qflist.new` | Experimental previewer for qflist. Uses vim buffers             |
+| `previewers.vim_buffer_qflist.new` | Default previewer for qflist. Uses vim buffers                  |
-| `previewers.cat.new` (deprecated)  | Default previewer for files. Uses `cat`/`bat`                   |
+| `previewers.cat.new`               | Deprecated previewer for files. Uses `cat`/`bat`                |
-| `previewers.vimgrep.new` (deprecated) | Default previewer for grep and similar. Uses `cat`/`bat`     |
+| `previewers.vimgrep.new`           | Deprecated previewer for grep and similar. Uses `cat`/`bat`     |
-| `previewers.qflist.new` (deprecated) | Default previewer for qflist. Uses `cat`/`bat`                |
+| `previewers.qflist.new`            | Deprecated previewer for qflist. Uses `cat`/`bat`               |
-| .................................. | Your next awesome previewer here :D                             |
 
 The default previewers are from now on `vim_buffer_` previewers. They use vim buffers for displaying files
 and use tree-sitter or regex for file highlighting.
@@ -475,7 +469,6 @@ autocmd User TelescopePreviewerLoaded setlocal wrap
 | `sorters.get_levenshtein_sorter`   | Using Levenshtein distance algorithm (don't use :D)             |
 | `sorters.get_fzy_sorter`           | Using fzy algorithm                                             |
 | `sorters.fuzzy_with_index_bias`    | Used to list stuff with consideration to when the item is added |
-| .................................. | Your next awesome sorter here :D                                |
 
 A `Sorter` is called by the `Picker` on each item returned by the `Finder`. It
 return a number, which is equivalent to the "distance" between the current
@@ -497,7 +490,6 @@ We have some built in themes but are looking for more cool options.
 | Themes                   | Description                                                           |
 |--------------------------|-----------------------------------------------------------------------|
 | `themes.get_dropdown`    | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png)|
-| ...                      | Your next awesome theme here :D                                       |
 
 
 To use a theme, simply append it to a built-in function:
@@ -723,7 +715,4 @@ To checkout the default values of the highlight groups, checkout `plugin/telesco
 ## Contributing
 
 All contributions are welcome! Just open a pull request.
-<!-- TODO: add plugin documentation -->
+Please read [CONTRIBUTING.md](./COONTRIBUTING.md)
-When approved,
-  changes in the user interface and new built-in functions
-  will need to be reflected in the documentation and in `README.md`.

doc/telescope.txt

@@ -180,6 +180,11 @@ actions.move_to_top({prompt_bufnr})                    *actions.move_to_top()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.open_qflist()                                  *actions.open_qflist()*
+    Open the quickfix list
+
+
+
 actions.remove_selection({prompt_bufnr})          *actions.remove_selection()*
     Remove current entry from multi select
 
@@ -516,6 +521,9 @@ horizontal and vertical layouts):
   - preview_width:
     - Change the width of Telescope's preview window
 
+  - scroll_speed:
+    - Change the scrolling speed of the previewer
+
 layout_strategies.center()                        *layout_strategies.center()*
     Centered layout wih smaller default sizes (I think)
 

lua/telescope/actions/init.lua

@@ -144,13 +144,11 @@ function actions.toggle_selection(prompt_bufnr)
 end
 
 function actions.preview_scrolling_up(prompt_bufnr)
-  -- TODO: Make number configurable.
+  action_set.scroll_previewer(prompt_bufnr, -1)
-  action_state.get_current_picker(prompt_bufnr).previewer:scroll_fn(-30)
 end
 
 function actions.preview_scrolling_down(prompt_bufnr)
-  -- TODO: Make number configurable.
+  action_set.scroll_previewer(prompt_bufnr, 1)
-  action_state.get_current_picker(prompt_bufnr).previewer:scroll_fn(30)
 end
 
 function actions.center(_)
@@ -413,6 +411,16 @@ actions.send_to_qflist = function(prompt_bufnr)
   vim.fn.setqflist(qf_entries, 'r')
 end
 
+actions.smart_send_to_qflist = function(prompt_bufnr)
+  local picker = action_state.get_current_picker(prompt_bufnr)
+  if table.getn(picker:get_multi_selection()) > 0 then
+    actions.send_selected_to_qflist(prompt_bufnr)
+  else
+    actions.send_to_qflist(prompt_bufnr)
+  end
+end
+
+--- Open the quickfix list
 actions.open_qflist = function(_)
   vim.cmd [[copen]]
 end

lua/telescope/actions/set.lua

@@ -2,6 +2,7 @@ local a = vim.api
 
 local log = require('telescope.log')
 local path = require('telescope.path')
+local state = require('telescope.state')
 
 local action_state = require('telescope.actions.state')
 
@@ -124,6 +125,18 @@ set.edit = function(prompt_bufnr, command)
   end
 end
 
+--- Scrolls the previewer up or down
+---@param prompt_bufnr number: The prompt bufnr
+---@param direction number: The direction of the scrolling
+--      Valid directions include: "1", "-1"
+set.scroll_previewer = function (prompt_bufnr, direction)
+  local status = state.get_status(prompt_bufnr)
+  local default_speed = vim.api.nvim_win_get_height(status.preview_win) / 2
+  local speed = status.picker.layout_config.scroll_speed or default_speed
+
+  action_state.get_current_picker(prompt_bufnr).previewer:scroll_fn(math.floor(speed * direction))
+end
+
 -- ==================================================
 -- Transforms modules and sets the corect metatables.
 -- ==================================================

lua/telescope/pickers/layout_strategies.lua

@@ -53,6 +53,9 @@
 ---
 ---   - preview_width:
 ---     - Change the width of Telescope's preview window
+---
+---   - scroll_speed:
+---     - Change the scrolling speed of the previewer
 ---@brief ]]
 
 local config = require('telescope.config')
@@ -99,6 +102,7 @@ layout_strategies.horizontal = function(self, max_columns, max_lines)
     height_padding = "How many cells to pad the height",
     preview_width = "(Resolvable): Determine preview width",
     mirror = "Flip the location of the results/prompt and preview windows",
+    scroll_speed = "The speed when scrolling through the previewer",
   })
 
   local initial_options = self:_get_initial_window_options()
@@ -266,6 +270,7 @@ layout_strategies.vertical = function(self, max_columns, max_lines)
     height_padding = "How many cells to pad the height",
     preview_height = "(Resolvable): Determine preview height",
     mirror = "Flip the locations of the results and prompt windows",
+    scroll_speed = "The speed when scrolling through the previewer",
   })
 
   local initial_options = self:_get_initial_window_options()