Metadata-Version: 2.0
Name: raiseorlaunch
Version: 1.0.0
Summary: A run-or-raise-application-launcher for i3 window manager.
Home-page: https://github.com/open-dynaMIX/raiseorlaunch
Author: Fabio Rämi
Author-email: fabio@dynamix-tontechnik.ch
License: MIT
Description-Content-Type: UNKNOWN
Keywords: i3 i3wm launcher run-or-raise navigation workspace scratchpad
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Requires-Dist: i3-py

raiseorlaunch
=============

.. image:: https://img.shields.io/pypi/v/raiseorlaunch.svg
      :target: https://pypi.python.org/pypi/raiseorlaunch/

.. image:: https://img.shields.io/pypi/pyversions/raiseorlaunch.svg
      :target: https://pypi.python.org/pypi/raiseorlaunch/

A run-or-raise-application-launcher for
`i3 window manager <https://i3wm.org/>`__.

Features
--------

- If a provided application is running, focus it's window, otherwise run it
- Provide a regex for window class, instance and/or title to compare with
  running windows
- Optionally enable case-insensitive comparison
- Optionally provide a workspace to use for raising and running
- Optionally use the scratchpad for raising and running
- workspace\_auto\_back\_and\_forth (if enabled) remains functional

Installation
------------

Repositories
************

raiseorlaunch is in `PyPI <https://pypi.python.org/pypi/raiseorlaunch/>`__,
so you can just

::

    pip install raiseorlaunch

For Arch Linux users it's also available in the
`AUR <https://aur.archlinux.org/packages/raiseorlaunch/>`__.

Manual
******

Dependencies
~~~~~~~~~~~~

- `i3-py <https://github.com/ziberna/i3-py>`__

Install
~~~~~~~~~~~~

Installing it directly with the setup.py creates a script-entry-point that
adds ~150ms delay. That's not acceptable for this kind of application.

This can be prevented, if creating a wheel first and installing that (needs
`wheel <https://pypi.python.org/pypi/wheel>`__ and
`pip <https://pypi.python.org/pypi/pip>`__):

.. code:: shell

    python setup.py bdist_wheel
    pip install ./dist/raiseorlaunch-${VERSION}-py2.py3-none-any.whl

Run without installation
~~~~~~~~~~~~~~~~~~~~~~~~

You can also just run raiseorlaunch without installing it:

.. code:: shell

    python -m raiseorlaunch ${OPTIONS}

or:

.. code:: shell

    ./raiseorlaunch/__main__.py ${OPTIONS}

Usage and options
-----------------

::

    usage: raiseorlaunch [-h] [-c WM_CLASS] [-s WM_INSTANCE] [-t WM_TITLE]
                         [-e COMMAND] [--no-startup-id] [-w WORKSPACE] [-r] [-i]
                         [-d] [-v]

    A run-or-raise-application-launcher for i3 window manager.

    optional arguments:
      -h, --help            show this help message and exit
      -c WM_CLASS, --class WM_CLASS
                            the window class regex
      -s WM_INSTANCE, --instance WM_INSTANCE
                            the window instance regex
      -t WM_TITLE, --title WM_TITLE
                            the window title regex
      -e COMMAND, --exec COMMAND
                            command to run with exec. If omitted, -c, -s or -t
                            will be used (lower-case). The command will always be
                            quoted, so make sure you properly escape internal
                            quotation marks. See the README for examples. Careful:
                            The command will not be checked prior to execution!
      --no-startup-id       use --no-startup-id when running command with exec
      -w WORKSPACE, --workspace WORKSPACE
                            workspace to use
      -r, --scratch         use scratchpad
      -i, --ignore-case     ignore case when comparing
      -d, --debug           display debug messages
      -v, --version         show program's version number and exit

Examples
--------

CLI
***

Run or raise Firefox:

.. code:: shell

    raiseorlaunch -c Firefox -s Navigator

Use the workspace `SL` for sublime text:

.. code:: shell

    raiseorlaunch -w SL -c "^Sublime" -s sublime_text -e subl

Raise or launch SpeedCrunch and use the scratchpad:

.. code:: shell

    raiseorlaunch -r -c SpeedCrunch

i3 bindsym
**********

In i3 config you can define a bindsym like that:

.. code::

    bindsym ${KEYS} exec --no-startup-id raiseorlaunch ${OPTIONS}

e.g.

.. code::

    bindsym $mod+s exec --no-startup-id raiseorlaunch -w SL -c "^Sublime" -s sublime_text -e subl

for binding `$mod+s` to raise or launch sublime text.

Escaping quotation marks
------------------------

If using a single-word command like `qutebrowser`, no quotation marks are
necessary. But for more complicated commands you will need them.

If the command itself also contains quotes, they need to get escaped properly.

Here are some exmaples:

On the CLI
**********
::

    raiseorlaunch -w 1 -c some_class -e "notify-send \\\"Hello, i3; from $USER\\\"; notify-send \\\"another message;\\\"" --no-startup-id
                                        ^ using double-quotes                 ^ three backslashes
    raiseorlaunch -w 1 -c some_class -e 'notify-send \"Hello, i3; from $USER\"; notify-send \"another message;\"' --no-startup-id
                                        ^ using single-quotes               ^ one backslash

Using bindsym
*************
When using raiseorlaunch with `exec`, things will get even a little more crazy.

In this examples we need to use `--no-startup-id` for execing raiseorlaunch. We
also need the same flag for raiseorlaunch, because the command run with it also
doesn't support startup-notifications.

::

    bindsym $mod+c exec --no-startup-id "raiseorlaunch -w 1 -c some_class -e 'notify-send \\\\"Hello, i3; from $USER\\\\"; notify-send \\\\"another message;\\\\"' --no-startup-id"
                                                                             ^ use single-quotes for -e             ^ four backslashes


Known problems
--------------

Keybindings steal focus when fired. This can have a negative impact with
applications that listen to FocusOut events and hide. This is due to `how X
works <https://github.com/i3/i3/issues/2843#issuecomment-316173601>`__.

Example:
********

When using Guake Terminal with "Hide on lose focus" enabled, raiseorlaunch
behaves as if the underlying window is focused.


