Update display config methods

README.md

@@ -146,7 +146,7 @@ require('telescope').setup{
     selection_strategy = "reset",
     sorting_strategy = "descending",
     layout_strategy = "horizontal",
-    layout_defaults = {
+    layout_config = {
       horizontal = {
         mirror = false,
       },
@@ -204,7 +204,7 @@ EOF
 | `sorting_strategy`     | Where first selection should be located.              | descending/ascending       |
 | `layout_strategy`      | How the telescope is drawn.                           | [supported layouts](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts) |
 | `winblend`             | How transparent is the telescope window should be.    | NUM                        |
-| `layout_defaults`      | Extra settings for fine-tuning how your layout looks  | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts#layout-defaults) |
+| `layout_config`        | Extra settings for fine-tuning how your layout looks  | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts#layout-defaults) |
 | `width`                | TODO                                                  | NUM                        |
 | `preview_cutoff`       | TODO                                                  | NUM                        |
 | `results_height`       | TODO                                                  | NUM                        |

doc/telescope.txt

@@ -25,6 +25,40 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: '  '
 
+                                         *telescope.defaults.layout_config*
+    layout_config: ~
+          Determines the default configuration values for layout strategies.
+          See |telescope.layout| for details of the configurations options for
+          each strategy.
+
+          Allows setting defaults for all strategies as top level options and
+          for overriding for specific options.
+          For example, the default values below set the default width to 80% of
+          the screen width for all strategies except 'center', which has width
+          of 50% of the screen width.
+
+          Default:
+          {
+            width = 0.8,
+            horizontal = {
+              height = 0.9,
+            },
+            vertical = {
+              height = 0.9,
+            },
+            center = {
+              width = 0.5
+            }
+          }
+
+
+                                       *telescope.defaults.layout_strategy*
+    layout_strategy: ~
+        Determines the default layout of Telescope pickers.
+        See |telescope.layout| for details of the available strategies.
+
+        Default: 'horizontal'
+
                                          *telescope.defaults.prompt_prefix*
     prompt_prefix: ~
         Will be shown in front of the prompt.
@@ -304,6 +338,46 @@ action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker(
 
 
 
+================================================================================
+                                                             *telescope.resolve*
+
+Provides "resolver functions" to allow more customisable inputs for options.
+
+resolver.resolve_height()                          *resolver.resolve_height()*
+    Converts input to a function that returns the height. The input must take
+    one of four forms:
+    1. 0 <= number < 1 This means total height as a percentage.
+    2. 1 <= number This means total height as a fixed number.
+    3. function Must have signature: function(self, max_columns, max_lines):
+       number
+    4. table of the form: {padding = `foo`} where `foo` has one of the previous
+       three forms. The height is then set to be the remaining space after
+       padding. The returned function will have signature: function(self,
+       max_columns, max_lines): number
+
+
+
+resolver.resolve_width()                            *resolver.resolve_width()*
+    Converts input to a function that returns the width. The input must take
+    one of four forms:
+    1. 0 <= number < 1 This means total width as a percentage.
+    2. 1 <= number This means total width as a fixed number.
+    3. function Must have signature: function(self, max_columns, max_lines):
+       number
+    4. table of the form: {padding = `foo`} where `foo` has one of the previous
+       three forms. The height is then set to be the remaining space after
+       padding. The returned function will have signature: function(self,
+       max_columns, max_lines): number
+
+
+
+resolver.win_option()                                  *resolver.win_option()*
+    Win option always returns a table with preview, results, and prompt. It
+    handles many different ways. Some examples are as follows:
+
+
+
+
 ================================================================================
                                                           *telescope.previewers*
 
@@ -616,11 +690,13 @@ horizontal and vertical layouts):
       - If using vertical: if `true`, swaps the location of the results and 
         prompt windows
 
-  - width_padding:
-    - How many cells to pad the width of Telescope's layout window
+  - width:
+    - How wide to make Telescope's layout window
+    - Resolvable: see |resolver.resolve_width()|
 
-  - height_padding:
-    - How many cells to pad the height of Telescope's layout window
+  - height:
+    - How tall to make Telescope's layout window
+    - Resolvable: see |resolver.resolve_height()|
 
   - preview_width:
     - Change the width of Telescope's preview window
@@ -629,48 +705,73 @@ horizontal and vertical layouts):
     - Change the scrolling speed of the previewer
 
 layout_strategies.horizontal()                *layout_strategies.horizontal()*
-    Horizontal previewer
-
-      +-------------+--------------+
-      |             |              |
-      |   Results   |              |
-      |             |    Preview   |
-      |             |              |
-      +-------------|              |
-      |   Prompt    |              |
-      +-------------+--------------+
+    Horizontal previewer has two columns, one for the preview and one for the
+    prompt and results.
+
+    ┌──────────────────────────────────────────────────┐
+    │                                                  │
+    │    ┌───────────────────┐┌───────────────────┐    │
+    │    │                   ││                   │    │
+    │    │                   ││                   │    │
+    │    │                   ││                   │    │
+    │    │      Results      ││                   │    │
+    │    │                   ││      Preview      │    │
+    │    │                   ││                   │    │
+    │    │                   ││                   │    │
+    │    └───────────────────┘│                   │    │
+    │    ┌───────────────────┐│                   │    │
+    │    │      Prompt       ││                   │    │
+    │    └───────────────────┘└───────────────────┘    │
+    │                                                  │
+    └──────────────────────────────────────────────────┘
 
 
 
 layout_strategies.center()                        *layout_strategies.center()*
-    Centered layout wih smaller default sizes (I think)
-
-       +--------------+
-       |    Preview   |
-       +--------------+
-       |    Prompt    |
-       +--------------+
-       |    Result    |
-       |    Result    |
-       |    Result    |
-       +--------------+
+    Centered layout with a combined block of the prompt and results aligned to
+    the middle of the screen. The preview window is then placed in the
+    remaining space above. Particularly useful for creating dropdown menus (try
+    using `theme=get_dropdown`).
+
+    ┌──────────────────────────────────────────────────┐
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Preview                |    │
+    │    |                 Preview                |    │
+    │    └────────────────────────────────────────┘    │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Prompt                 |    │
+    │    ├────────────────────────────────────────┤    │
+    │    |                 Result                 |    │
+    │    |                 Result                 |    │
+    │    └────────────────────────────────────────┘    │
+    │                                                  │
+    │                                                  │
+    │                                                  │
+    │                                                  │
+    └──────────────────────────────────────────────────┘
 
 
 
 layout_strategies.vertical()                    *layout_strategies.vertical()*
-    Vertical perviewer stacks the items on top of each other.
-
-       +-----------------+
-       |    Previewer    |
-       |    Previewer    |
-       |    Previewer    |
-       +-----------------+
-       |     Result      |
-       |     Result      |
-       |     Result      |
-       +-----------------+
-       |     Prompt      |
-       +-----------------+
+    Vertical previewer stacks the items on top of each other. Particularly
+    useful with thinner windows.
+
+    ┌──────────────────────────────────────────────────┐
+    │                                                  │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Preview                |    │
+    │    |                 Preview                |    │
+    │    |                 Preview                |    │
+    │    └────────────────────────────────────────┘    │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Result                 |    │
+    │    |                 Result                 |    │
+    │    └────────────────────────────────────────┘    │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Prompt                 |    │
+    │    └────────────────────────────────────────┘    │
+    │                                                  │
+    └──────────────────────────────────────────────────┘
 
 
 

lua/telescope/config.lua

@@ -85,15 +85,54 @@ function config.set_defaults(defaults)
     - "cycle" (default)
     - "limit"]])
 
-  set("layout_strategy", "horizontal")
-  set("layout_defaults", {})
-
-  set("width", 0.75)
+  set("layout_strategy", "horizontal", [[
+    Determines the default layout of Telescope pickers.
+    See |telescope.layout| for details of the available strategies.
+
+    Default: 'horizontal']])
+  set("layout_config", {
+    width = 0.8,
+    horizontal = {
+      height = 0.9,
+    },
+    vertical = {
+      height = 0.9,
+    },
+    center = {
+      width = 0.5
+    }
+  },[[
+    Determines the default configuration values for layout strategies.
+    See |telescope.layout| for details of the configurations options for
+    each strategy.
+
+    Allows setting defaults for all strategies as top level options and
+    for overriding for specific options.
+    For example, the default values below set the default width to 80% of
+    the screen width for all strategies except 'center', which has width
+    of 50% of the screen width.
+
+    Default:
+    {
+      width = 0.8,
+      horizontal = {
+        height = 0.9,
+      },
+      vertical = {
+        height = 0.9,
+      },
+      center = {
+        width = 0.5
+      }
+    }
+  ]])
+
+  -- set("width", 0.75)
   set("winblend", 0)
   set("prompt_position", "bottom")
   set("preview_cutoff", 120)
 
-  set("results_height", 1)
+  set("results_height", 5)
   set("results_width", 0.8)
 
   set("prompt_prefix", "> ", [[

lua/telescope/config/resolve.lua

@@ -1,3 +1,8 @@
+---@tag telescope.resolve
+
+---@brief [[
+--- Provides "resolver functions" to allow more customisable inputs for options.
+---@brief ]]
 
 --[[
 
@@ -40,7 +45,7 @@ height =
 
     3. function(picker, columns, lines)
         -> returns one of the above options
-        return max.min(110, max_rows * .5)
+        return math.min(110, max_rows * .5)
 
         if columns > 120 then
             return 110
@@ -88,8 +93,7 @@ That's the next step to scrolling.
 local get_default = require('telescope.utils').get_default
 
 local resolver = {}
-
-local _resolve_map = {
+local _simple_resolve_map = {
   -- Booleans
   [function(val) return val == false end] = function(selector, val)
     return function(...)
@@ -128,6 +132,44 @@ local _resolve_map = {
   end,
 }
 
+-- Make a copy of the "simple" _resolve_map that we can add to to make the "full" _resolve_map.
+local _resolve_map = vim.deepcopy(_simple_resolve_map)
+
+-- Add padding option
+_resolve_map[function(val) return type(val) == 'table' and val['padding'] ~= nil end] = function(selector, val)
+  local resolve_pad = function(value)
+    for k, v in pairs(_simple_resolve_map) do
+      if k(value) then
+        return v(selector, value)
+      end
+    end
+
+    error('invalid configuration option for padding:' .. tostring(value))
+  end
+
+  return function(...)
+    local selected = select(selector, ...)
+    local padding = resolve_pad(val['padding'])
+    return math.floor(selected - 2 * padding(...))
+  end
+end
+
+
+--- Converts input to a function that returns the height.
+--- The input must take one of four forms:
+--- 1. 0 <= number < 1
+---     This means total height as a percentage.
+--- 2. 1 <= number
+---     This means total height as a fixed number.
+--- 3. function
+---     Must have signature:
+---       function(self, max_columns, max_lines): number
+--- 4. table of the form:
+---       {padding = `foo`}
+---     where `foo` has one of the previous three forms.
+---     The height is then set to be the remaining space after padding.
+--- The returned function will have signature:
+---     function(self, max_columns, max_lines): number
 resolver.resolve_height = function(val)
   for k, v in pairs(_resolve_map) do
     if k(val) then
@@ -138,6 +180,21 @@ resolver.resolve_height = function(val)
   error('invalid configuration option for height:' .. tostring(val))
 end
 
+--- Converts input to a function that returns the width.
+--- The input must take one of four forms:
+--- 1. 0 <= number < 1
+---     This means total width as a percentage.
+--- 2. 1 <= number
+---     This means total width as a fixed number.
+--- 3. function
+---     Must have signature:
+---       function(self, max_columns, max_lines): number
+--- 4. table of the form:
+---       {padding = `foo`}
+---     where `foo` has one of the previous three forms.
+---     The height is then set to be the remaining space after padding.
+--- The returned function will have signature:
+---     function(self, max_columns, max_lines): number
 resolver.resolve_width = function(val)
   for k, v in pairs(_resolve_map) do
     if k(val) then