# i3-quickterm
[](https://repology.org/project/python:i3-quickterm/versions)
A small drop-down terminal for [i3wm](https://i3wm.org/) and [sway](https://swaywm.org/)
## Features
* use your favourite terminal emulator
* can select a shell with [dmenu](http://tools.suckless.org/dmenu/) / [rofi](https://github.com/DaveDavenport/rofi)
* adapt to screen width
* multi-monitor aware
## Installation
Via pip:
```
pip install i3-quickterm
```
Or check the the repology badge above to check if it is packaged by your distribution.
## Usage
When launched, it will minimize the quickterm on the current screen if there is one. Otherwise, it will either prompt the user for the shell to open or use the one supplied in argument.
If the requested shell is already opened on another screen, it will be moved on the current screen.
It is recommended to map it to an i3 binding:
```
# with prompt
bindsym $mod+p exec i3-quickterm
# always bring up standard shell, without the menu
bindsym $mod+b exec i3-quickterm shell
```
## Configuration
The configuration is read from `~/.config/i3-quickterm/config.json` or `~/.config/i3/i3-quickterm.json`.
* `menu`: the dmenu-compatible application used to select the shell
* `term`: the terminal emulator of choice
* `history`: a file to save the last-used shells order, last-used ordering is disabled if set to null
* `ratio`: the percentage of the screen height to use
* `pos`: where to pop the terminal (`top` or `bottom`)
* `shells`: registered shells (`{ name: command }`)
`term` can be either:
- the name of a terminal from the [supported list](#supported-terminals).
- `auto` to select the first existing terminal of the list above (only to provide friendler defaults, not recommended otherwise)
- a format string, like this one: `urxvt -t {title} -e {expanded}` with the correct arguments format of your terminal. Some terminals, like xfce4-terminal need the command argument to be passed as a string. In this case, replace `{expanded}` by `{string}`
`menu`, `term`, `history` and `shell` can contain placeholders for environment variables: `{$var}`.
Unspecified keys are inherited from the defaults:
```
{
"menu": "rofi -dmenu -p 'quickterm: ' -no-custom -auto-select",
"term": "auto",
"history": "{$HOME}/.cache/i3-quickterm/shells.order",
"ratio": 0.25,
"pos": "top",
"shells": {
"js": "node",
"python": "ipython3 --no-banner",
"shell": "{$SHELL}"
}
}
```
## Supported terminals
* alacritty
* foot
* gnome-terminal
* kitty
* roxterm
* st
* terminator
* termite
* urxvt
* urxvtc
* xfce4-terminal
* xterm
If you'd like to add another terminal (or correct an error), please open a pull request.
## Requirements
* python >= 3.8
* i3 >= v3.11 or sway >= 1.2
* [i3ipc-python](https://i3ipc-python.readthedocs.io/en/latest/) >= v2.0.1
* dmenu or rofi (optional)
Raw data
{
"_id": null,
"home_page": "https://github.com/lbonn/i3-quickterm",
"name": "i3-quickterm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "i3 i3wm extensions add-ons",
"author": "lbonn",
"author_email": "github@lbonnans.net",
"download_url": "https://files.pythonhosted.org/packages/4d/e9/26f6784344d42c337f282795a74d2e03fbdb5fec13e41ca714fb2d7ae646/i3-quickterm-1.2.tar.gz",
"platform": null,
"description": "# i3-quickterm\n\n[](https://repology.org/project/python:i3-quickterm/versions)\n\nA small drop-down terminal for [i3wm](https://i3wm.org/) and [sway](https://swaywm.org/)\n\n## Features\n\n* use your favourite terminal emulator\n* can select a shell with [dmenu](http://tools.suckless.org/dmenu/) / [rofi](https://github.com/DaveDavenport/rofi)\n* adapt to screen width\n* multi-monitor aware\n\n## Installation\n\nVia pip:\n\n```\npip install i3-quickterm\n```\n\nOr check the the repology badge above to check if it is packaged by your distribution.\n\n## Usage\n\nWhen launched, it will minimize the quickterm on the current screen if there is one. Otherwise, it will either prompt the user for the shell to open or use the one supplied in argument.\n\nIf the requested shell is already opened on another screen, it will be moved on the current screen.\n\nIt is recommended to map it to an i3 binding:\n\n```\n# with prompt\nbindsym $mod+p exec i3-quickterm\n# always bring up standard shell, without the menu\nbindsym $mod+b exec i3-quickterm shell\n```\n\n## Configuration\n\nThe configuration is read from `~/.config/i3-quickterm/config.json` or `~/.config/i3/i3-quickterm.json`.\n\n* `menu`: the dmenu-compatible application used to select the shell\n* `term`: the terminal emulator of choice\n* `history`: a file to save the last-used shells order, last-used ordering is disabled if set to null\n* `ratio`: the percentage of the screen height to use\n* `pos`: where to pop the terminal (`top` or `bottom`)\n* `shells`: registered shells (`{ name: command }`)\n\n`term` can be either:\n- the name of a terminal from the [supported list](#supported-terminals).\n- `auto` to select the first existing terminal of the list above (only to provide friendler defaults, not recommended otherwise)\n- a format string, like this one: `urxvt -t {title} -e {expanded}` with the correct arguments format of your terminal. Some terminals, like xfce4-terminal need the command argument to be passed as a string. In this case, replace `{expanded}` by `{string}`\n\n`menu`, `term`, `history` and `shell` can contain placeholders for environment variables: `{$var}`.\n\nUnspecified keys are inherited from the defaults:\n\n```\n{\n \"menu\": \"rofi -dmenu -p 'quickterm: ' -no-custom -auto-select\",\n \"term\": \"auto\",\n \"history\": \"{$HOME}/.cache/i3-quickterm/shells.order\",\n \"ratio\": 0.25,\n \"pos\": \"top\",\n \"shells\": {\n \"js\": \"node\",\n \"python\": \"ipython3 --no-banner\",\n \"shell\": \"{$SHELL}\"\n }\n}\n```\n\n## Supported terminals\n\n* alacritty\n* foot\n* gnome-terminal\n* kitty\n* roxterm\n* st\n* terminator\n* termite\n* urxvt\n* urxvtc\n* xfce4-terminal\n* xterm\n\nIf you'd like to add another terminal (or correct an error), please open a pull request.\n\n## Requirements\n\n* python >= 3.8\n* i3 >= v3.11 or sway >= 1.2\n* [i3ipc-python](https://i3ipc-python.readthedocs.io/en/latest/) >= v2.0.1\n* dmenu or rofi (optional)\n",
"bugtrack_url": null,
"license": "",
"summary": "A small drop-down terminal for i3 and sway",
"version": "1.2",
"project_urls": {
"Bug Reports": "https://github.com/lbonn/i3-quickterm/issues",
"Homepage": "https://github.com/lbonn/i3-quickterm",
"Source": "https://github.com/lbonn/i3-quickterm"
},
"split_keywords": [
"i3",
"i3wm",
"extensions",
"add-ons"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "718191760bf47235161caf59a7903f56d90a3787aead09d85f2c2fd6211ac55a",
"md5": "14400590f66412e4051101fb1d4e26cc",
"sha256": "df10d6cc333f08891a59ea0f105a8623bc4169461f63c48ef30dddc32b946d89"
},
"downloads": -1,
"filename": "i3_quickterm-1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14400590f66412e4051101fb1d4e26cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8031,
"upload_time": "2024-02-06T12:19:55",
"upload_time_iso_8601": "2024-02-06T12:19:55.926819Z",
"url": "https://files.pythonhosted.org/packages/71/81/91760bf47235161caf59a7903f56d90a3787aead09d85f2c2fd6211ac55a/i3_quickterm-1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4de926f6784344d42c337f282795a74d2e03fbdb5fec13e41ca714fb2d7ae646",
"md5": "407f0e609d4a3eb077d1199c0fbfb33b",
"sha256": "ce764456a84d72fa552990b9fa3aca686535ec3899b1c20812758fcd0551f4ce"
},
"downloads": -1,
"filename": "i3-quickterm-1.2.tar.gz",
"has_sig": false,
"md5_digest": "407f0e609d4a3eb077d1199c0fbfb33b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9873,
"upload_time": "2024-02-06T12:19:59",
"upload_time_iso_8601": "2024-02-06T12:19:59.103114Z",
"url": "https://files.pythonhosted.org/packages/4d/e9/26f6784344d42c337f282795a74d2e03fbdb5fec13e41ca714fb2d7ae646/i3-quickterm-1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-06 12:19:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lbonn",
"github_project": "i3-quickterm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "i3-quickterm"
}
JSON
