feat: Consistent and sensible layout_config (#922)
* 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
@@ -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()|
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user