Add docs for individual layouts
Also changelog entry for the splits layout Fixes #2308
This commit is contained in:
Kovid Goyal
parent
6670cc1534
commit
c0d0062ef8
@ -4,6 +4,13 @@ Changelog
|
|||||||
|kitty| is a feature full, cross-platform, *fast*, GPU based terminal emulator.
|
|kitty| is a feature full, cross-platform, *fast*, GPU based terminal emulator.
|
||||||
To update |kitty|, :doc:`follow the instructions <binary>`.
|
To update |kitty|, :doc:`follow the instructions <binary>`.
|
||||||
|
|
||||||
|
0.17.0 [future]
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
- A new :ref:`splits_layout` to arrange windows in arbitrary splits
|
||||||
|
(:iss:`2308`)
|
||||||
|
|
||||||
|
|
||||||
0.16.0 [2020-01-28]
|
0.16.0 [2020-01-28]
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
|
|||||||
200
docs/layouts.rst
200
docs/layouts.rst
@ -22,12 +22,200 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
|
|||||||
layout
|
layout
|
||||||
|
|
||||||
|
|
||||||
You can resize windows inside layouts. Press :sc:`start_resizing_window` (also :kbd:`⌘+r` on macOS) to
|
There are many different layouts available. They are all enabled by default,
|
||||||
enter resizing mode and follow the on-screen instructions. In a given window
|
you can switch layouts using :sc:`next_layout`. To control which layouts
|
||||||
layout only some operations may be possible for a particular window. For
|
are available use :opt:`enabled_layouts` the first listed layout becomes
|
||||||
example, in the Tall layout you can make the first window wider/narrower, but
|
the default. Individual layouts and how to use them are described below.
|
||||||
not taller/shorter. Note that what you are resizing is actually not a window,
|
|
||||||
but a row/column in the layout, all windows in that row/column will be resized.
|
.. contents::
|
||||||
|
|
||||||
|
|
||||||
|
The Stack Layout
|
||||||
|
------------------
|
||||||
|
|
||||||
|
This is the simplest layout it displays a single window using all available
|
||||||
|
space, other windows are hidden behind it. It has no options::
|
||||||
|
|
||||||
|
enabled_layouts stack
|
||||||
|
|
||||||
|
|
||||||
|
The Tall Layout
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Displays one (or optionally more) full height windows on the left half of the
|
||||||
|
screen. Remaining windows are tiled vertically on the right half of the screen.
|
||||||
|
There are options to control how the screen is split horizontally ``bias``
|
||||||
|
(an integer between ``10`` and ``90``) and options to control how many
|
||||||
|
full-height windows there are ``full_size`` (a positive integer). The syntax
|
||||||
|
for the options is shown below::
|
||||||
|
|
||||||
|
enabled_layouts tall:bias=50;full_size=1
|
||||||
|
|
||||||
|
┌──────────────┬───────────────┐
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ ├───────────────┤
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ ├───────────────┤
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
└──────────────┴───────────────┘
|
||||||
|
|
||||||
|
The Fat Layout
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Displays one (or optionally more) full width windows on the top half of the
|
||||||
|
screen. Remaining windows are tiled horizontally on the bottom half of the screen.
|
||||||
|
There are options to control how the screen is split vertically ``bias``
|
||||||
|
(an integer between ``10`` and ``90``) and options to control how many
|
||||||
|
full-height windows there are ``full_size`` (a positive integer). The syntax
|
||||||
|
for the options is shown below::
|
||||||
|
|
||||||
|
enabled_layouts fat:bias=50;full_size=1
|
||||||
|
|
||||||
|
┌──────────────────────────────┐
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
├─────────┬──────────┬─────────┤
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
└─────────┴──────────┴─────────┘
|
||||||
|
|
||||||
|
|
||||||
|
The Grid Layout
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Display windows in a balanced grid with all windows the same size except the
|
||||||
|
last column if there are not enough windows to fill the grid. Has no options::
|
||||||
|
|
||||||
|
enabled_layouts grid
|
||||||
|
|
||||||
|
┌─────────┬──────────┬─────────┐
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
├─────────┼──────────┼─────────┤
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
└─────────┴──────────┴─────────┘
|
||||||
|
|
||||||
|
|
||||||
|
.. _splits_layout:
|
||||||
|
|
||||||
|
The Splits Layout
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
This is the most flexible layout. You can create any arrangement of windows
|
||||||
|
by splitting exiting windows repeatedly. To best use this layout you should
|
||||||
|
define a few extra keybindings in :file:`kitty.conf`::
|
||||||
|
|
||||||
|
map F5 launch --location=hsplit
|
||||||
|
map F6 launch --location=vsplit
|
||||||
|
map F7 layout_action rotate
|
||||||
|
|
||||||
|
map shift+up move_window up
|
||||||
|
map shift+left move_window left
|
||||||
|
map shift+right move_window right
|
||||||
|
map shift+down move_window down
|
||||||
|
|
||||||
|
map ctrl+left neighboring_window left
|
||||||
|
map ctrl+right neighboring_window right
|
||||||
|
map ctrl+up neighboring_window up
|
||||||
|
map ctrl+down neighboring_window down
|
||||||
|
|
||||||
|
Now you can create horizontal and vertical splits by using :kbd:`F5` and
|
||||||
|
:kbd:`F6`. You can move them around using :kbd:`shift+arrow keys`
|
||||||
|
and you can move focus to neighboring windows using :kbd:`ctrl+arrow keys`.
|
||||||
|
And you can switch an existing split from horizontal to vertical and vice versa
|
||||||
|
using :kbd:`F7`. Finally, windows can be resized using :ref:`window_resizing`.
|
||||||
|
|
||||||
|
This layout takes one option, ``split_axis`` that control if new windows
|
||||||
|
are placed into vertical or horizontal splits, by default::
|
||||||
|
|
||||||
|
enabled_layouts splits:split_axis=horizontal
|
||||||
|
|
||||||
|
┌──────────────┬───────────────┐
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ ├───────┬───────┤
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ ├───────┴───────┤
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
└──────────────┴───────────────┘
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
The Horizontal Layout
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
All windows are shown side by side. Has no options::
|
||||||
|
|
||||||
|
enabled_layouts horizontal
|
||||||
|
|
||||||
|
┌─────────┬──────────┬─────────┐
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
└─────────┴──────────┴─────────┘
|
||||||
|
|
||||||
|
|
||||||
|
The Vertical Layout
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
All windows are shown one below the other. Has no options::
|
||||||
|
|
||||||
|
enabled_layouts vertical
|
||||||
|
|
||||||
|
┌──────────────────────────────┐
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
├──────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
├──────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
└──────────────────────────────┘
|
||||||
|
|
||||||
|
|
||||||
|
.. _window_resizing:
|
||||||
|
|
||||||
|
Resizing windows
|
||||||
|
------------------
|
||||||
|
|
||||||
|
You can resize windows inside layouts. Press :sc:`start_resizing_window` (also
|
||||||
|
:kbd:`⌘+r` on macOS) to enter resizing mode and follow the on-screen
|
||||||
|
instructions. In a given window layout only some operations may be possible
|
||||||
|
for a particular window. For example, in the Tall layout you can make the first
|
||||||
|
window wider/narrower, but not taller/shorter. Note that what you are resizing
|
||||||
|
is actually not a window, but a row/column in the layout, all windows in that
|
||||||
|
row/column will be resized.
|
||||||
|
|
||||||
You can also define shortcuts in :file:`kitty.conf` to make the active window
|
You can also define shortcuts in :file:`kitty.conf` to make the active window
|
||||||
wider, narrower, taller, or shorter by mapping to the ``resize_window``
|
wider, narrower, taller, or shorter by mapping to the ``resize_window``
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user