diff --git a/docs/index.rst b/docs/index.rst index 7a5c54587..dd3d4f690 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -219,57 +219,26 @@ Reset background opacity :sc:`reset_background_opacity` Layouts ---------- -A layout is an arrangement of multiple *windows*. You can create a new window +A layout is an arrangement of multiple kitty *windows* inside a top-level OS window. You can create a new window using the :sc:`new_window` key combination. -Currently, there are five layouts available, +Currently, there are six layouts available: * **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom * **Grid** -- All windows are shown in a grid * **Horizontal** -- All windows are shown side-by-side +* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits * **Stack** -- Only a single maximized window is shown at a time * **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right * **Vertical** -- All windows are shown one below the other -You can switch between layouts using the :sc:`next_layout` key combination. You can -also create shortcuts to select particular layouts, and choose which layouts -you want to enable/disable, see :ref:`conf-kitty-shortcuts.layout` for examples. +By default, all layouts are enabled and you can switch between layouts using +the :sc:`next_layout` key combination. You can also create shortcuts to select +particular layouts, and choose which layouts you want to enable/disable, see +:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in +:opt:`enabled_layouts` becomes the default layout. -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 -wider, narrower, taller, or shorter by mapping to the ``resize_window`` -action, for example:: - - map ctrl+left resize_window narrower - map ctrl+right resize_window wider - map ctrl+up resize_window taller - map ctrl+down resize_window shorter 3 - -The ``resize_window`` action has a second, optional argument to control -the resizing increment (a positive integer that defaults to 1). - - -Some layouts take options to control their behavior. For example, the ``fat`` -and ``tall`` layouts accept the ``bias`` and ``full_size`` options to control -how the available space is split up. -To specify the option, in :opt:`kitty.conf ` use:: - - enabled_layouts tall:bias=70;full_size=2 - -This will have ``2`` instead of a single tall window, that occupy ``70%`` -instead of ``50%`` of available width. ``bias`` can be any number between 10 -and 90. - -Writing a new layout only requires about a hundred lines of code, so if there -is some layout you want, take a look at `layout.py -`_ and submit -a pull request! +For more details on the layouts and how to use them see :doc:`layouts`. .. _kittens: diff --git a/docs/layouts.rst b/docs/layouts.rst new file mode 100644 index 000000000..3f01398e9 --- /dev/null +++ b/docs/layouts.rst @@ -0,0 +1,59 @@ +Layouts +============ + +kitty has the ability to define its own windows that can be tiled next to each +other in arbitrary arrangements, based on *Layouts*, see below for examples: + + +.. figure:: screenshots/screenshot.png + :alt: Screenshot, showing three programs in the 'Tall' layout + :align: center + :scale: 100% + + Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout + + +.. figure:: screenshots/splits.png + :alt: Screenshot, showing windows in the 'Splits' layout + :align: center + :scale: 100% + + Screenshot, showing windows with arbitrary arrangement in the 'Splits' + layout + + +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 +wider, narrower, taller, or shorter by mapping to the ``resize_window`` +action, for example:: + + map ctrl+left resize_window narrower + map ctrl+right resize_window wider + map ctrl+up resize_window taller + map ctrl+down resize_window shorter 3 + +The ``resize_window`` action has a second, optional argument to control +the resizing increment (a positive integer that defaults to 1). + + +Some layouts take options to control their behavior. For example, the ``fat`` +and ``tall`` layouts accept the ``bias`` and ``full_size`` options to control +how the available space is split up. +To specify the option, in :opt:`kitty.conf ` use:: + + enabled_layouts tall:bias=70;full_size=2 + +This will have ``2`` instead of a single tall window, that occupy ``70%`` +instead of ``50%`` of available width. ``bias`` can be any number between 10 +and 90. + +Writing a new layout only requires about a hundred lines of code, so if there +is some layout you want, take a look at `layout.py +`_ and submit +a pull request! diff --git a/docs/screenshots/splits.png b/docs/screenshots/splits.png new file mode 100644 index 000000000..1d53add86 Binary files /dev/null and b/docs/screenshots/splits.png differ