mirror of
https://github.com/kovidgoyal/kitty
synced 2026-07-26 02:02:14 +02:00
Docs: Improve the documentation for kittens
Add more text roles and links. Add an example that broadcasts only to other windows in the current tab. Initial capitalization of the key names in the kbd text role. Add Python type hints for custom kittens. Note about hyperlink support for ls on macOS. Add description text for show_key.
This commit is contained in:
pagedown
@@ -1,21 +1,20 @@
|
||||
Custom kittens
|
||||
=================
|
||||
|
||||
You can easily create your own kittens to extend kitty. They are just
|
||||
terminal programs written in Python. When launching a kitten, kitty will
|
||||
open an overlay window over the current window and optionally pass the
|
||||
contents of the current window/scrollback to the kitten over its :file:`STDIN`.
|
||||
The kitten can then perform whatever actions it likes, just as a normal
|
||||
terminal program. After execution of the kitten is complete, it has access
|
||||
to the running kitty instance so it can perform arbitrary actions
|
||||
such as closing windows, pasting text, etc.
|
||||
You can easily create your own kittens to extend kitty. They are just terminal
|
||||
programs written in Python. When launching a kitten, kitty will open an overlay
|
||||
window over the current window and optionally pass the contents of the current
|
||||
window/scrollback to the kitten over its :file:`STDIN`. The kitten can then
|
||||
perform whatever actions it likes, just as a normal terminal program. After
|
||||
execution of the kitten is complete, it has access to the running kitty instance
|
||||
so it can perform arbitrary actions such as closing windows, pasting text, etc.
|
||||
|
||||
Let's see a simple example of creating a kitten. It will ask the user for some
|
||||
input and paste it into the terminal window.
|
||||
|
||||
Create a file in the kitty config folder, :file:`~/.config/kitty/mykitten.py`
|
||||
(you might need to adjust the path to wherever the kitty config folder is on
|
||||
your machine).
|
||||
Create a file in the kitty config directory, :file:`~/.config/kitty/mykitten.py`
|
||||
(you might need to adjust the path to wherever the :ref:`kitty config directory
|
||||
<confloc>` is on your machine).
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
@@ -43,11 +42,12 @@ Now in :file:`kitty.conf` add the lines::
|
||||
map ctrl+k kitten mykitten.py
|
||||
|
||||
|
||||
Start kitty and press :kbd:`ctrl+k` and you should see the kitten running.
|
||||
The best way to develop your own kittens is to modify one of the built in
|
||||
kittens. Look in the kittens sub-directory of the kitty source code for those.
|
||||
Or see below for a list of :ref:`third-party kittens <external_kittens>`,
|
||||
that other kitty users have created.
|
||||
Start kitty and press :kbd:`Ctrl+K` and you should see the kitten running.
|
||||
The best way to develop your own kittens is to modify one of the built-in
|
||||
kittens. Look in the `kittens sub-directory
|
||||
<https://github.com/kovidgoyal/kitty/tree/master/kittens>`__ of the kitty source
|
||||
code for those. Or see below for a list of :ref:`third-party kittens
|
||||
<external_kittens>`, that other kitty users have created.
|
||||
|
||||
|
||||
Passing arguments to kittens
|
||||
@@ -60,36 +60,40 @@ You can pass arguments to kittens by defining them in the map directive in
|
||||
|
||||
These will be available as the ``args`` parameter in the ``main()`` and
|
||||
``handle_result()`` functions. Note also that the current working directory
|
||||
of the kitten is set to the working directory of whatever program is
|
||||
running in the active kitty window. The special argument ``@selection``
|
||||
is replaced by the currently selected text in the active kitty window.
|
||||
of the kitten is set to the working directory of whatever program is running in
|
||||
the active kitty window. The special argument ``@selection`` is replaced by the
|
||||
currently selected text in the active kitty window.
|
||||
|
||||
|
||||
Passing the contents of the screen to the kitten
|
||||
---------------------------------------------------
|
||||
|
||||
If you would like your kitten to have access to the contents of the screen
|
||||
and/or the scrollback buffer, you just need to add an annotation to the ``handle_result()``
|
||||
function, telling kitty what kind of input your kitten would like. For example:
|
||||
and/or the scrollback buffer, you just need to add an annotation to the
|
||||
``handle_result()`` function, telling kitty what kind of input your kitten would
|
||||
like. For example:
|
||||
|
||||
.. code-block:: py
|
||||
|
||||
from typing import List
|
||||
from kitty.boss import Boss
|
||||
|
||||
# in main, STDIN is for the kitten process and will contain
|
||||
# the contents of the screen
|
||||
def main(args):
|
||||
def main(args: List[str]) -> str:
|
||||
return sys.stdin.read()
|
||||
|
||||
# in handle_result, STDIN is for the kitty process itself, rather
|
||||
# than the kitten process and should not be read from.
|
||||
from kittens.tui.handler import result_handler
|
||||
@result_handler(type_of_input='text')
|
||||
def handle_result(args, stdin_data, target_window_id, boss):
|
||||
def handle_result(args: List[str], stdin_data: str, target_window_id: int, boss: Boss) -> None:
|
||||
pass
|
||||
|
||||
|
||||
This will send the plain text of the active window to the kitten's
|
||||
:file:`STDIN`. There are many other types of input you can ask for,
|
||||
described in the table below:
|
||||
:file:`STDIN`. There are many other types of input you can ask for, described in
|
||||
the table below:
|
||||
|
||||
.. table:: Types of input to kittens
|
||||
:align: left
|
||||
@@ -121,31 +125,35 @@ and ``first_output`` gives the output of the first command currently on screen.
|
||||
These can also be combined with ``screen`` and ``ansi`` for formatting.
|
||||
|
||||
.. note::
|
||||
For the types based on the output of a command,
|
||||
:ref:`shell_integration` is required.
|
||||
For the types based on the output of a command, :ref:`shell_integration` is
|
||||
required.
|
||||
|
||||
|
||||
Using kittens to script kitty, without any terminal UI
|
||||
-----------------------------------------------------------
|
||||
|
||||
If you would like your kitten to script kitty, without bothering to write a
|
||||
terminal program, you can tell the kittens system to run the
|
||||
``handle_result()`` function without first running the ``main()`` function.
|
||||
terminal program, you can tell the kittens system to run the ``handle_result()``
|
||||
function without first running the ``main()`` function.
|
||||
|
||||
For example, here is a kitten that "zooms/unzooms" the current terminal window
|
||||
by switching to the stack layout or back to the previous layout. This is
|
||||
For example, here is a kitten that "zooms in/zooms out" the current terminal
|
||||
window by switching to the stack layout or back to the previous layout. This is
|
||||
equivalent to the builtin :ac:`toggle_layout` action.
|
||||
|
||||
Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
|
||||
Create a Python file in the :ref:`kitty config directory <confloc>`,
|
||||
:file:`~/.config/kitty/zoom_toggle.py`
|
||||
|
||||
.. code-block:: py
|
||||
|
||||
def main(args):
|
||||
from typing import List
|
||||
from kitty.boss import Boss
|
||||
|
||||
def main(args: List[str]) -> str:
|
||||
pass
|
||||
|
||||
from kittens.tui.handler import result_handler
|
||||
@result_handler(no_ui=True)
|
||||
def handle_result(args, answer, target_window_id, boss):
|
||||
def handle_result(args: List[str], answer: str, target_window_id: int, boss: Boss) -> None:
|
||||
tab = boss.active_tab
|
||||
if tab is not None:
|
||||
if tab.current_layout.name == 'stack':
|
||||
@@ -154,7 +162,7 @@ Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
|
||||
tab.goto_layout('stack')
|
||||
|
||||
|
||||
Now in kitty.conf add::
|
||||
Now in :file:`kitty.conf` add::
|
||||
|
||||
map f11 kitten zoom_toggle.py
|
||||
|
||||
@@ -165,7 +173,7 @@ layout, by simply adding the line::
|
||||
boss.toggle_fullscreen()
|
||||
|
||||
|
||||
To the ``handle_result()`` function, above.
|
||||
to the ``handle_result()`` function, above.
|
||||
|
||||
|
||||
.. _send_mouse_event:
|
||||
@@ -173,7 +181,7 @@ To the ``handle_result()`` function, above.
|
||||
Sending mouse events
|
||||
--------------------
|
||||
|
||||
If the program running in a window is receiving mouse events you can simulate
|
||||
If the program running in a window is receiving mouse events, you can simulate
|
||||
those using::
|
||||
|
||||
from kitty.fast_data_types import send_mouse_event
|
||||
@@ -200,15 +208,15 @@ that type, and will return ``True`` if it sent the event, and ``False`` if not.
|
||||
Debugging kittens
|
||||
--------------------
|
||||
|
||||
The part of the kitten that runs in ``main()`` is just a normal program and
|
||||
the output of print statements will be visible in the kitten window. Or
|
||||
alternately, you can use::
|
||||
The part of the kitten that runs in ``main()`` is just a normal program and the
|
||||
output of print statements will be visible in the kitten window. Or alternately,
|
||||
you can use::
|
||||
|
||||
from kittens.tui.loop import debug
|
||||
debug('whatever')
|
||||
|
||||
The ``debug()`` function is just like ``print()`` except that the output
|
||||
will appear in the ``STDOUT`` of the kitty process inside which the kitten is
|
||||
The ``debug()`` function is just like ``print()`` except that the output will
|
||||
appear in the ``STDOUT`` of the kitty process inside which the kitten is
|
||||
running.
|
||||
|
||||
The ``handle_result()`` part of the kitten runs inside the kitty process.
|
||||
@@ -216,12 +224,13 @@ The output of print statements will go to the ``STDOUT`` of the kitty process.
|
||||
So if you run kitty from another kitty instance, the output will be visible
|
||||
in the first kitty instance.
|
||||
|
||||
|
||||
Adding options to kittens
|
||||
----------------------------
|
||||
|
||||
If you would like to use kitty's config framework to make your kittens
|
||||
configurable, you will need some boilerplate. In the directory
|
||||
of your kitten make the following files.
|
||||
configurable, you will need some boilerplate. Put the following files in the
|
||||
directory of your kitten.
|
||||
|
||||
:file:`kitten_options_definition.py`
|
||||
|
||||
@@ -311,8 +320,9 @@ You can parse and read the options in your kitten using the following code:
|
||||
opts.config_overrides = overrides
|
||||
return opts
|
||||
|
||||
See the code for the builtin diff kitten for examples of creating more options
|
||||
and keyboard shortcuts.
|
||||
See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
|
||||
for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
|
||||
options and keyboard shortcuts.
|
||||
|
||||
.. _external_kittens:
|
||||
|
||||
@@ -320,7 +330,8 @@ Kittens created by kitty users
|
||||
---------------------------------------------
|
||||
|
||||
`vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
|
||||
Allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
|
||||
Allows you to navigate seamlessly between vim and kitty splits using a
|
||||
consistent set of hotkeys.
|
||||
|
||||
`smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
|
||||
Makes the kitty scroll bindings work in full screen applications
|
||||
|
||||
Reference in New Issue
Block a user