mirror of
https://github.com/kovidgoyal/kitty.git
synced 2024-09-11 14:45:31 +03:00
166 lines
5.9 KiB
ReStructuredText
166 lines
5.9 KiB
ReStructuredText
Scripting the mouse click
|
|
======================================================
|
|
|
|
|kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
|
|
generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
|
|
:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on
|
|
these hyperlinks in |kitty|.
|
|
|
|
You can tell kitty to take arbitrarily many, complex actions when a link is
|
|
clicked. Let us illustrate with some examples, first. Create the file
|
|
:file:`~/.config/kitty/open-actions.conf` with the following:
|
|
|
|
.. code:: conf
|
|
|
|
# Open any image in the full kitty window by clicking on it
|
|
protocol file
|
|
mime image/*
|
|
action launch --type=overlay kitten icat --hold -- ${FILE_PATH}
|
|
|
|
Now, run ``ls --hyperlink=auto`` in kitty and click on the filename of an
|
|
image, holding down :kbd:`ctrl+shift`. It will be opened over the current
|
|
window. Press any key to close it.
|
|
|
|
.. note::
|
|
|
|
The :program:`ls` comes with macOS does not support hyperlink, you need to
|
|
install `GNU Coreutils <https://www.gnu.org/software/coreutils/>`__. If you
|
|
install it via `Homebrew <https://formulae.brew.sh/formula/coreutils>`__, it
|
|
will be :program:`gls`.
|
|
|
|
Each entry in :file:`open-actions.conf` consists of one or more
|
|
:ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
|
|
``action`` entries. In the example above kitty uses the :doc:`launch <launch>`
|
|
action which can be used to run external programs. Entries are separated by
|
|
blank lines.
|
|
|
|
Actions are very powerful, anything that you can map to a key combination in
|
|
:file:`kitty.conf` can be used as an action. You can specify more than one
|
|
action per entry if you like, for example:
|
|
|
|
|
|
.. code:: conf
|
|
|
|
# Tail a log file (*.log) in a new OS Window and reduce its font size
|
|
protocol file
|
|
ext log
|
|
action launch --title ${FILE} --type=os-window tail -f -- ${FILE_PATH}
|
|
action change_font_size current -2
|
|
|
|
|
|
In the action specification you can expand environment variables, as shown in
|
|
the examples above. In addition to regular environment variables, there are
|
|
some special variables, documented below:
|
|
|
|
``URL``
|
|
The full URL being opened
|
|
|
|
``FILE_PATH``
|
|
The path portion of the URL (unquoted)
|
|
|
|
``FILE``
|
|
The file portion of the path of the URL (unquoted)
|
|
|
|
``FRAGMENT``
|
|
The fragment (unquoted), if any of the URL or the empty string.
|
|
|
|
``NETLOC``
|
|
The net location aka hostname (unquoted), if any of the URL or the empty string.
|
|
|
|
``URL_PATH``
|
|
The path, query and fragment portions of the URL, without any
|
|
unquoting.
|
|
|
|
``EDITOR``
|
|
The terminal based text editor. The configured :opt:`editor` in
|
|
:file:`kitty.conf` is preferred.
|
|
|
|
``SHELL``
|
|
The path to the shell. The configured :opt:`shell` in :file:`kitty.conf` is
|
|
preferred, without arguments.
|
|
|
|
.. note::
|
|
You can use the :opt:`action_alias` option just as in :file:`kitty.conf` to
|
|
define aliases for frequently used actions.
|
|
|
|
|
|
.. _matching_criteria:
|
|
|
|
Matching criteria
|
|
------------------
|
|
|
|
An entry in :file:`open-actions.conf` must have one or more matching criteria.
|
|
URLs that match all criteria for an entry will trigger that entry's actions.
|
|
Processing stops at the first matching entry, so put more specific matching
|
|
criteria at the start of the list. Entries in the file are separated by blank
|
|
lines. The various available criteria are:
|
|
|
|
``protocol``
|
|
A comma separated list of protocols, for example: ``http, https``. If
|
|
absent, there is no constraint on protocol.
|
|
|
|
``url``
|
|
A regular expression that must match against the entire (unquoted) URL
|
|
|
|
``fragment_matches``
|
|
A regular expression that must match against the fragment (part after #) in
|
|
the URL
|
|
|
|
``mime``
|
|
A comma separated list of MIME types, for example: ``text/*, image/*,
|
|
application/pdf``. You can add MIME types to kitty by creating a file named
|
|
:file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
|
|
Useful if your system MIME database does not have definitions you need. This
|
|
file is in the standard format of one definition per line, like:
|
|
``text/plain rst md``. Note that the MIME type for directories is
|
|
``inode/directory``. MIME types are detected based on file extension, not
|
|
file contents.
|
|
|
|
``ext``
|
|
A comma separated list of file extensions, for example: ``jpeg, tar.gz``
|
|
|
|
``file``
|
|
A shell glob pattern that must match the filename, for example:
|
|
``image-??.png``
|
|
|
|
|
|
.. _launch_actions:
|
|
|
|
Scripting the opening of files with kitty on macOS
|
|
-------------------------------------------------------
|
|
|
|
On macOS you can use :guilabel:`Open With` in Finder or drag and drop files and
|
|
URLs onto the kitty dock icon to open them with kitty. The default actions are:
|
|
|
|
* Open text files in your editor and images using the icat kitten.
|
|
* Run shell scripts in a shell
|
|
* Open SSH urls using the ssh command
|
|
|
|
These actions can also be executed from the command line by running::
|
|
|
|
kitty +open file_or_url another_url ...
|
|
|
|
# macOS only
|
|
open -a kitty.app file_or_url another_url ...
|
|
|
|
Since macOS lacks an official interface to set default URL scheme handlers,
|
|
kitty has a command you can use for it. The first argument for is the URL
|
|
scheme, and the second optional argument is the bundle id of the app, which
|
|
defaults to kitty, if not specified. For example:
|
|
|
|
.. code-block:: sh
|
|
|
|
# Set kitty as the handler for ssh:// URLs
|
|
kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' ssh
|
|
# Set someapp as the handler for xyz:// URLs
|
|
kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier
|
|
|
|
You can customize these actions by creating a :file:`launch-actions.conf` file
|
|
in the :ref:`kitty config directory <confloc>`, just like the
|
|
:file:`open-actions.conf` file above. For example:
|
|
|
|
.. literalinclude:: ../kitty/open_actions.py
|
|
:language: conf
|
|
:start-at: # Open script files
|
|
:end-before: '''.splitlines()))
|