Metadata-Version: 2.4
Name: i3_find_or_open
Version: 0.6.4
Summary: A command-line utility that helps you bind keys to find and display a window, or open it if there is no instance running, in i3wm.
License: GPL-3.0-only
License-File: LICENSE
Author: Hector Brown
Author-email: hectorjbrown@protonmail.com
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: argparse (>=1.4.0,<2.0.0)
Requires-Dist: i3ipc (>=2.2.1,<3.0.0)
Description-Content-Type: text/markdown

# i3-find-or-open

This repo provides a command-line tool: `i3-find-or-open` that can find a
window by regex in your i3wm instance, and display it, or execute any command
if it is not open.

It is intended to help you bind keys that will reliably show you a window,
whether or not it is open already, but technically it is capable of showing you
any window (which is uniquely identifiable by either title or class), or
running an arbitrary command if it is not open.

## Installation

i3-find-or-open is available on
[PyPI](https://pypi.org/project/i3_find_or_open/), and the best way to install
it (if you don't want to break your system python installation) is to use
[pipx](https://pypa.github.io/pipx/installation/) (N.B. there is an Arch
package `python-pipx` to install this with).

```sh
pipx install i3-find-or-open
```

Note that if you want to bind keys in i3 to this program, it will need to be
installed for all users:

```sh
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install i3-find-or-open
```

*(or you could bind `$HOME/.local/bin/i3-find-or-open` if you'd rather not
install it for everybody)*

If you do want to risk breaking your system python, you could just use `pip`.

Or, you could install it in a virtual environment yourself (note that this is
all `pipx` is doing, but you might rather manage these environments manually).

## Usage

Let's say I wanted to use this to bind `$mod+o` to open my Obsidian vault
(called "vault"):

```i3config
bindsym $mod+o exec --no-startup-id "i3-find-or-open '^.* - vault - Obsidian v([1-9]|\.)+$' 'obsidian'"
```

It's worth noting that the title regex you use will usually have to be quite
specific when running from a command line, as the title of your terminal
emulator will likely include the full command string (make use of `^`, and `$`
tokens where possible).

Some other examples, taken from my i3 config:

```i3config
bindsym $mod+t exec --no-startup-id "i3-find-or-open 'timetable\.ods — LibreOffice Calc' 'libreoffice --norestore ~/icl/timetable.ods'"
bindsym $mod+q exec --no-startup-id "i3-find-or-open 'qBittorrent' 'qbittorrent'"
```

You can also use the `-c` flag to match a window class instead of title if the
title completely changes (like for the Spotify app).

```i3config
bindsym $mod+s exec --no-startup-id "i3-find-or-open -c 'Spotify' 'spotify-launcher'"
```

You can use the `-t` flag to toggle scratchpad windows (i.e. to mimic the
effect of the `scratchpad show` command, but just for your targeted window).
Keeping this off (as is the default) will make sure the behaviour is such that
your keybinding will always show you the targeted window, no matter what.

Title and class information about any open window can be found with the `xprop` command.

