leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Consistent and sensible layout_config (#922)

Browse Source 
* feat: Consistent and sensible layout_config

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

* [WIP]: Thu 17 Jun 2021 03:36:44 PM EDT

* [WIP]: Thu 17 Jun 2021 03:38:11 PM EDT

* layout_default -> layout_defaults

* remove options from bug repot

* Conni2461 suggestions: part 1

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

* Conni2461 suggestions: part 2

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

* Linting

* Improve deprecation checks

- Move `layout_defaults` handling to `deprecated.lua`
- Check for "layout keys" outside of `layout_config` on `setup`

* fixup: Just add a few more words

Co-authored-by: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com>
Co-authored-by: Github Actions <actions@github>
This commit is contained in:
TJ DeVries
2021-07-01 02:41:58 -07:00
committed by GitHub
parent e5bd4963da
commit 5a53ec5c2f
16 changed files with 1300 additions and 529 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
doc/telescope.txt
View File

@@ -19,13 +19,27 @@ telescope.setup({opts}) *telescope.setup()*
Valid keys for {opts.defaults}
*telescope.defaults.border*
border: ~
Boolean defining if borders are added to Telescope windows.
Default: true
*telescope.defaults.default_mappings*
default_mappings: ~
Not recommended to use except for advanced users.
Will allow you to completely remove all of telescope's default maps
and use your own.
*telescope.defaults.dynamic_preview_title*
dynamic_preview_title: ~
Will change the title of the preview window dynamically, where it
is supported. Means the preview window will for example show the
full filename.
Will change the title of the preview window dynamically, where it
is supported. Means the preview window will for example show the
full filename.
Default: false
Default: false
*telescope.defaults.entry_prefix*
@@ -34,6 +48,94 @@ 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: {
center = {
preview_cutoff = 40
},
height = 0.9,
horizontal = {
preview_cutoff = 120,
prompt_position = "bottom"
},
vertical = {
preview_cutoff = 40
},
width = 0.8
}
*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.mappings*
mappings: ~
Your mappings to override telescope's default mappings.
Format is:
{
mode = { ..keys }
}
where {mode} is the one character letter for a mode
('i' for insert, 'n' for normal).
For example:
mappings = {
i = {
["<esc>"] = require('telescope.actions').close,
},
}
To disable a keymap, put [map] = false
So, to not map "<C-n>", just put
...,
["<C-n>"] = false,
...,
Into your config.
otherwise, just set the mapping to the function that you want it to be.
...,
["<C-i>"] = require('telescope.actions').select_default,
...,
If the function you want is part of `telescope.actions`, then you can simply give a string.
For example, the previous option is equivalent to:
...,
["<C-i>"] = "select_default",
...,
You can also add other mappings using tables with `type = "command"`.
For example:
...,
["jj"] = { "<esc>", type = "command" },
["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
...,
*telescope.defaults.prompt_prefix*
prompt_prefix: ~
Will be shown in front of the prompt.
@@ -478,7 +580,7 @@ require("telescope").setup {
mappings = {
i = {
["<c-d>"] = require("telescope.actions").delete_buffer,
-- or right hand side can also be a the name of the action as string
-- or right hand side can also be the name of the action as string
["<c-d>"] = "delete_buffer",
},
n = {
@@ -1118,6 +1220,52 @@ 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. For
example, if the window has height 50, and the input is {padding = 5},
the height returned will be `40 = 50 - 2*5`
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 width is then set to be the remaining space after padding. For
example, if the window has width 100, and the input is {padding = 5},
the width returned will be `90 = 100 - 2*5`
The returned function will have signature: function(self, max_columns,
max_lines): number
================================================================================
*telescope.previewers*
@@ -1450,7 +1598,7 @@ Layout strategies are different functions to position telescope.
All layout strategies are functions with the following signature:
function(picker, columns, lines)
function(picker, columns, lines, layout_config)
-- Do some calculations here...
return {
preview = preview_configuration
@@ -1460,99 +1608,167 @@ All layout strategies are functions with the following signature:
end
Parameters: ~
- picker : A Picker object. (docs coming soon)
- columns : number Columns in the vim window
- lines : number Lines in the vim window
- picker : A Picker object. (docs coming soon)
- columns : (number) Columns in the vim window
- lines : (number) Lines in the vim window
- layout_config : (table) The configuration values specific to the picker.
TODO: I would like to make these link to `telescope.layout_strategies.*`, but
it's not yet possible.
This means you can create your own layout strategy if you want! Just be aware
for now that we may change some APIs or interfaces, so they may break if you
create your own.
Available layout strategies include:
- horizontal:
- See |layout_strategies.horizontal|
A good method for creating your own would be to copy one of the strategies that
most resembles what you want from
"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo.
- vertical:
- See |layout_strategies.vertical|
- flex:
- See |layout_strategies.flex|
Available tweaks to the settings in layout defaults include (can be applied to
horizontal and vertical layouts):
- mirror (default is `false`):
- Flip the view of the current layout:
- If using horizontal: if `true`, swaps the location of the
results/prompt window and preview window
- 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
- height_padding:
- How many cells to pad the height of Telescope's layout window
- preview_width:
- Change the width of Telescope's preview window
- scroll_speed:
- Change the scrolling speed of the previewer
layout_strategies.horizontal() *layout_strategies.horizontal()*
Horizontal previewer
Horizontal layout has two columns, one for the preview and one for the
prompt and results.
+-------------+--------------+
| | |
| Results | |
| | Preview |
| | |
+-------------| |
| Prompt | |
+-------------+--------------+
┌──────────────────────────────────────────────────┐
│ │
│ ┌───────────────────┐┌───────────────────┐ │
│ │ ││ │ │
│ │ ││ │ │
│ │ ││ │ │
│ │ Results ││ │ │
│ │ ││ Preview │ │
│ │ ││ │ │
│ │ ││ │ │
│ └───────────────────┘│ │ │
│ ┌───────────────────┐│ │ │
│ │ Prompt ││ │ │
│ └───────────────────┘└───────────────────┘ │
│ │
└──────────────────────────────────────────────────┘
`picker.layout_config` shared options:
- height:
- How tall to make Telescope's entire layout
- See |resolver.resolve_height()|
- mirror: Flip the location of the results/prompt and preview windows
- scroll_speed: The number of lines to scroll through the previewer
- width:
- How wide to make Telescope's entire layout
- See |resolver.resolve_width()|
`picker.layout_config` unique options:
- preview_cutoff: When columns are less than this value, the preview will be disabled
- preview_width:
- Change the width of Telescope's preview window
- See |resolver.resolve_width()|
- prompt_position:
- Where to place prompt window.
- Available Values: 'bottom', 'top'
layout_strategies.center() *layout_strategies.center()*
Centered layout wih smaller default sizes (I think)
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 (see
|telescope.themes| and |themes.get_dropdown()|`).
+--------------+
| Preview |
+--------------+
| Prompt |
+--------------+
| Result |
| Result |
| Result |
+--------------+
┌──────────────────────────────────────────────────┐
│ ┌────────────────────────────────────────┐ │
│ | Preview | │
│ | Preview | │
│ └────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────┐ │
│ | Prompt | │
│ ├────────────────────────────────────────┤ │
│ | Result | │
│ | Result | │
│ └────────────────────────────────────────┘ │
│ │
│ │
│ │
│ │
└──────────────────────────────────────────────────┘
`picker.layout_config` shared options:
- height:
- How tall to make Telescope's entire layout
- See |resolver.resolve_height()|
- mirror: Flip the location of the results/prompt and preview windows
- scroll_speed: The number of lines to scroll through the previewer
- width:
- How wide to make Telescope's entire layout
- See |resolver.resolve_width()|
`picker.layout_config` unique options:
- preview_cutoff: When lines are less than this value, the preview will be disabled
layout_strategies.vertical() *layout_strategies.vertical()*
Vertical perviewer stacks the items on top of each other.
Vertical layout stacks the items on top of each other. Particularly useful
with thinner windows.
+-----------------+
| Previewer |
| Previewer |
| Previewer |
+-----------------+
| Result |
| Result |
| Result |
+-----------------+
| Prompt |
+-----------------+
┌──────────────────────────────────────────────────┐
│ │
│ ┌────────────────────────────────────────┐ │
│ | Preview | │
│ | Preview | │
│ | Preview | │
│ └────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────┐ │
│ | Result | │
│ | Result | │
│ └────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────┐ │
│ | Prompt | │
│ └────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────┘
`picker.layout_config` shared options:
- height:
- How tall to make Telescope's entire layout
- See |resolver.resolve_height()|
- mirror: Flip the location of the results/prompt and preview windows
- scroll_speed: The number of lines to scroll through the previewer
- width:
- How wide to make Telescope's entire layout
- See |resolver.resolve_width()|
`picker.layout_config` unique options:
- preview_cutoff: When lines are less than this value, the preview will be disabled
- preview_height:
- Change the height of Telescope's preview window
- See |resolver.resolve_height()|
- prompt_position:
- (unimplemented, but we plan on supporting)
layout_strategies.flex() *layout_strategies.flex()*
Swap between `horizontal` and `vertical` strategies based on the window
width
- Supports `vertical` or `horizontal` features
Flex layout swaps between `horizontal` and `vertical` strategies based on
the window width
- Supports |layout_strategies.vertical| or |layout_strategies.horizontal|
features
Uses:
- flip_columns
- flip_lines
`picker.layout_config` shared options:
- height:
- How tall to make Telescope's entire layout
- See |resolver.resolve_height()|
- mirror: Flip the location of the results/prompt and preview windows
- scroll_speed: The number of lines to scroll through the previewer
- width:
- How wide to make Telescope's entire layout
- See |resolver.resolve_width()|
`picker.layout_config` unique options:
- flip_columns: The number of columns required to move to horizontal mode
- flip_lines: The number of lines required to move to horizontal mode
- horizontal: Options to pass when switching to horizontal layout
- vertical: Options to pass when switching to vertical layout
layout_strategies.bottom_pane() *layout_strategies.bottom_pane()*
Bottom pane can be used to create layouts similar to "ivy".
For an easy ivy configuration, see |themes.get_ivy()|

51
doc/telescope_changelog.txt Normal file
View File

@@ -0,0 +1,51 @@
================================================================================
*telescope.changelog*
# Changelog
*telescope.changelog-922*
Date: May 17, 2021
PR: https://github.com/nvim-telescope/telescope.nvim/pull/922
This is one of our largest breaking changes thus far, so I (TJ) am adding some
information here so that you can more easily update (without having to track
down the commit, etc.).
The goal of these breaking changes is to greatly simplify the way
configuration for layouts happen. This should make it much easier to configure
each picker, layout_strategy, and more. Please report any bugs or behavior
that is broken / confusing upstream and we can try and make the configuration
better.
|telescope.setup()| has changed `layout_defaults` -> `layout_config`.
This makes it so that the setup and the pickers share the same key,
otherwise it is too confusing which key is for which.
`picker:find()` now has different values available for configuring the UI.
All configuration for the layout must be passed in the key:
`layout_config`.
Previously, these keys were passed via `picker:find(opts)`, but should be
passed via `opts.layout_config` now.
- {height}
- {width}
- {prompt_position}
- {preview_cutoff}
These keys are removed:
- {results_height}: This key is no longer valid. Instead, use `height`
and the corresponding `preview_*` options for the layout strategy to
get the correct results height. This simplifies the configuration
for many of the existing strategies.
- {results_width}: This key actually never did anything. It was
leftover from some hacking that I had attempted before. Instead you
should be using something like the `preview_width` configuration
option for |layout_strategies.horizontal()|
You should get error messages when you try and use any of the above keys now.
vim:tw=78:ts=8:ft=help:norl: