PolytreeDE/rofi
1
0
Fork 0
mirror of https://github.com/davatorium/rofi.git synced 2024-11-18 13:54:36 -05:00
Code Releases Activity

Update to documentation by RaZ0rr-Two (#1495)

Browse source 
* Update readme 1 (manpages)

* Update 2 (create config.md)

* README update final 1

* Rename to CONFIG

* README update final 2

* small update

* Aligning the top to center

* Corrected dead links

* gif (mp4) added

Co-authored-by: RaZ0rr-Two <84911063+RaZ0rr-Two@users.noreply.github.com>
This commit is contained in:
Dave Davenport 2021-10-29 14:00:22 +02:00 committed by GitHub
parent 8db289d065
commit b1dff0c211
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 324 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

200
CONFIG.md Normal file
View file

@ -0,0 +1,200 @@
> # :warning: This page does not describe all of **ROFI**'s configuration options, just the most common usecase. For the full configuration options, check the manpages.
<br />
## :exclamation: Upgrade from old configuration format to new :exclamation:
In release after '2 Jan 2020' you can convert to the new configuration format by using the following command:
```bash
rofi -upgrade-config
```
This will create `~/.config/rofi/config.rasi` (or the default location for your system) with the previously configured options.
From 1.7.0 the old configuration format is no longer supported and the `-upgrade-config` option is no longer available.
<br />
# Where does the configuration live
Rofi's configurations, custom themes live in `${XDG_CONFIG_HOME}/rofi/`, on most systems this is `~/.config/rofi/`.
The name of the main configuration file is `config.rasi`. (`~/.config/rofi/config.rasi`).
# Create an empty configuration file
Open `~/.config/rofi/config.rasi` in your favorite text editor and add the following block:
```css
configuration {
}
```
You can now set the options in the `configuration` block.
# Create a configuration file from current setup
If you do not want to start from scratch, or want to migrate from older configuration format, you can get tell rofi to dumps it configuration:
```bash
rofi -dump-config > ~/.config/rofi/config.rasi
```
This will have all the possible settings and their current value.
If a value is the default value, the entry will be commented.
For example:
```css
configuration {
/* modi: "window,run,ssh,drun";*/
/* font: "mono 12";*/
/* location: 0;*/
/* yoffset: 0;*/
/* xoffset: 0;*/
/* fixed-num-lines: true;*/
... cut ...
/* ml-row-down: "ScrollDown";*/
/* me-select-entry: "MousePrimary";*/
/* me-accept-entry: "MouseDPrimary";*/
/* me-accept-custom: "Control+MouseDPrimary";*/
}
```
# Configuration file format
## Encoding
The encoding of the file is utf-8. Both Unix (`\n`) and windows (`\r\n`) newlines format are supported. But Unix is preferred.
## Comments
C and C++ file comments are supported.
* Anything after `// ` and before a newline is considered a comment.
* Everything between `/*` and `*/` is a comment.
Comments can be nested and the C comments can be inline.
The following is valid:
```
// Magic comment.
property: /* comment */ value;
```
However, this is not:
```
prop/*comment*/erty: value;
```
## White space
White space and newlines, like comments, are ignored by the parser.
This:
```
property: name;
```
Is identical to:
```
property :
name
;
```
## Data types
**ROFI**'s configuration supports several data formats:
### String
A string is always surrounded by double quotes (`"`). Between the quotes there can be any printable character.
For example:
```css
ml-row-down: "ScrollDown";
```
### Number
An integer may contain any full number.
For example:
```
eh: 2;
```
### Boolean
Boolean value is either `true` or `false`. This is case-sensitive.
For example:
```css
show-icons: true;
```
This is equal to the `-show-icons` option on the commandline, and `show-icons: false;` is equal to `-no-show-icons`.
### Character
Character value is always surrounded by single quotes (') and should contain a single character.
It supports escaping.
```css
matching-negate-char: '-';
```
### List
This is not supported by the old configuration system, but can be used in the **rasi** format.
A list starts with a '[' and ends with a ']'. The entries in the list are comma-separated.
The entry in the list single ASCII words.
```css
combi-modi: [window,drun];
```
For older versions you have :
```css
combi-modi: "window,drun";
```
# Get a list of all possible options
There are 2 ways to get a list of all options:
1. Dump the configuration file explained above. (`rofi -dump-config`)
2. Look at output of `rofi -h`.
To see what values an option support check the manpage, it describes most of them.
NOTE: not all options might be in the manpage, as options can be added at run-time. (f.e. by plugins).
# Splitting configuration over multiple files
It is possible to split configuration over multiple files using imports. For example in `~/.config/rofi/config.rasi`
```css
configuration {
}
@import "myConfig"
@theme "MyTheme"
```
Rofi will first parse the config block in `~/.config/rofi/config.rasi`, then parse `~/.config/rofi/myConfig.rasi` and then load the theme `myTheme`.\
More information can be obtained from **Themes** section\
Imports can be nested.

154
README.md
View file

@ -1,11 +1,19 @@
[![Issues](https://img.shields.io/github/issues/davatorium/rofi.svg)](https://github.com/davatorium/rofi/issues) <p align="center">
[![Forks](https://img.shields.io/github/forks/davatorium/rofi.svg)](https://github.com/davatorium/rofi/network) <a href="https://github.com/davatorium/rofi/issues"><img src="https://img.shields.io/github/issues/davatorium/rofi.svg"></a>
[![Stars](https://img.shields.io/github/stars/davatorium/rofi.svg)](https://github.com/davatorium/rofi/stargazers) <a href="https://img.shields.io/github/forks/davatorium/rofi.svg"><img src="https://img.shields.io/github/forks/davatorium/rofi.svg"></a>
[![Downloads](https://img.shields.io/github/downloads/davatorium/rofi/total.svg)](https://github.com/davatorium/rofi/releases) <a href="https://github.com/davatorium/rofi/stargazers"><img src="https://img.shields.io/github/stars/davatorium/rofi.svg"></a>
[![Forum](https://img.shields.io/badge/forum-online-green.svg)](https://github.com/davatorium/rofi/discussions) <a href="https://github.com/davatorium/rofi/releases"><img src="https://img.shields.io/github/downloads/davatorium/rofi/total.svg"></a>
[![Packages](https://repology.org/badge/tiny-repos/rofi.svg)](https://repology.org/metapackage/rofi/versions) <a href="https://github.com/davatorium/rofi/discussions"><img src="https://img.shields.io/badge/forum-online-green.svg"></a>
<a href="https://repology.org/metapackage/rofi/versions"><img src="https://repology.org/badge/tiny-repos/rofi.svg"></a>
</p>
<h1 align="center">
Rofi
</h1>
<p align="center"><i>A window switcher, Application launcher and dmenu replacement</i>.</p>
https://user-images.githubusercontent.com/84911063/139428874-fe182dd6-82c6-49b8-8da1-920ddda3d1ed.mp4
# A window switcher, Application launcher and dmenu replacement
**Rofi** started as a clone of simpleswitcher, written by [Sean Pringle](http://github.com/seanpringle/simpleswitcher) - a **Rofi** started as a clone of simpleswitcher, written by [Sean Pringle](http://github.com/seanpringle/simpleswitcher) - a
popup window switcher roughly based on [superswitcher](http://code.google.com/p/superswitcher/). popup window switcher roughly based on [superswitcher](http://code.google.com/p/superswitcher/).
@ -16,6 +24,34 @@ ssh-launcher, and can act as a drop-in dmenu replacement, making it a very versa
**Rofi**, like dmenu, will provide the user with a textual list of options where one or more can be selected. **Rofi**, like dmenu, will provide the user with a textual list of options where one or more can be selected.
This can either be running an application, selecting a window, or options provided by an external script. This can either be running an application, selecting a window, or options provided by an external script.
## What is rofi not?
Rofi is not:
* A UI toolkit.
* A library to be used in other applications.
* An application that can support every possible use-case. It tries to be generic enough to be usable by everybody.
* Specific functionality can be added using scripts or plugins, many exists.
* Just a dmenu replacement. The dmenu functionality is a nice 'extra' to **rofi**, not its main purpose.
# Table of Contents
- [Features](#features)
- [Modi](#modi)
- [Manpages]($manpage)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Usage](#usage)
- [Configuration](#configuration)
- [Themes]($themes)
- [Screenshots](#screenshots)
- [Wiki](#wiki)
- [Discussion places](#discussion-places)
# Features
Its main features are: Its main features are:
* Fully configurable keyboard navigation * Fully configurable keyboard navigation
@ -42,6 +78,8 @@ Its main features are:
* Easily extensible using scripts and plugins * Easily extensible using scripts and plugins
* Advanced Theming * Advanced Theming
# Modi
**Rofi** has several built-in modi implementing common use cases and can be extended by scripts (either called from **Rofi** has several built-in modi implementing common use cases and can be extended by scripts (either called from
**Rofi** or calling **Rofi**) or plugins. **Rofi** or calling **Rofi**) or plugins.
@ -58,6 +96,67 @@ Below is a list of the different modi:
**Rofi** is known to work on Linux and BSD. **Rofi** is known to work on Linux and BSD.
# Manpage
For more up to date information, please see the manpages. The other sections and links might have outdated information as they have relatively less maintainance than the manpages. So, if you come across any issues please consult manpages, [discussion](https://github.com/davatorium/rofi/discussions) and [issue traker](https://github.com/davatorium/rofi/issues?q=) before filing new issue.
* Manpages:
* [rofi](doc/rofi.1.markdown)
* [rofi-theme](doc/rofi-theme.5.markdown)
* [rofi-script](doc/rofi-script.5.markdown)
* [rofi-theme-selector](doc/rofi-theme-selector.1.markdown)
# Installation
Please see the [installation guide](https://github.com/davatorium/rofi/blob/next/INSTALL.md) for instructions on how to
install **Rofi**.
# Quickstart
## Usage
> **This section just gives a brief overview of the various options. To get the full set of options see the _manpages_ section above**
#### Running rofi
To launch **rofi** directly in a certain mode, specify a mode with `rofi -show <mode>`.
To show the `run` dialog:
rofi -show run
Or get the options from a script:
~/my_script.sh | rofi -dmenu
Specify an ordered, comma-separated list of modes to enable.
Enabled modes can be changed at runtime. Default key is `Ctrl+Tab`.
If no modes are specified, all configured modes will be enabled.
To only show the `run` and `ssh` launcher:
rofi -modi "run,ssh" -show run
The modi to combine in combi mode.
For syntax to `-combi-modi`, see `-modi`.
To get one merge view, of `window`,`run`, and `ssh`:
rofi -show combi -combi-modi "window,run,ssh" -modi combi
## Configuration
Generate a default configuration file
```
mkdir -p ~/.config/rofi
rofi -dump-config > ~/.config/rofi/config.rasi
```
This creates a file called `config.rasi` in the `~/.config/rofi/` folder. You can modify this file to set configuration settings and modify themes. `config.rasi` is the file rofi looks to by default.
Please see the [configuration guide](https://github.com/davatorium/rofi/blob/next/CONFIG.md) for a summary of configuration options. More detailed options are provided in the manpages.
## Themes
Please see the [themes](https://github.com/davatorium/rofi/wiki/themes) section from the [wiki](https://github.com/davatorium/rofi/wiki) for brief reference. More detailed options are provided in the [themes manpages](https://github.com/davatorium/rofi/blob/next/doc/rofi-theme.5.markdown).
# Screenshots # Screenshots
@ -65,32 +164,27 @@ Below is a list of the different modi:
![screenshot2](https://raw.githubusercontent.com/davatorium/rofi/next/releasenotes/1.6.0/icons2.png) ![screenshot2](https://raw.githubusercontent.com/davatorium/rofi/next/releasenotes/1.6.0/icons2.png)
![default](https://raw.githubusercontent.com/davatorium/rofi/next/releasenotes/1.4.0/rofi-no-fzf.png) ![default](https://raw.githubusercontent.com/davatorium/rofi/next/releasenotes/1.4.0/rofi-no-fzf.png)
# Manpage # Wiki
For more up to date information, please see the manpages: | ❗ **The Wiki is Community maintained and are not thoroughly tested** |
| --- |
* Manpages: [Go to wiki](https://github.com/davatorium/rofi/wiki) .
* [rofi](doc/rofi.1.markdown)
* [rofi-theme](doc/rofi-theme.5.markdown)
* [rofi-script](doc/rofi-script.5.markdown)
* [rofi-theme-selector](doc/rofi-theme-selector.1.markdown)
* Discussion places:
* [Reddit](https://reddit.com/r/qtools/)
* [GitHub Discussions](https://github.com/davatorium/rofi/discussions)
* IRC (#rofi on irc.libera.chat)
* [wiki](https://github.com/davatorium/rofi/wiki) (Currently unmaintained).
# Installation #### Contents
Please see the [installation guide](https://github.com/davatorium/rofi/blob/next/INSTALL.md) for instructions on how to * [User scripts](https://github.com/davatorium/rofi/wiki/User-scripts)
install **Rofi**. * [dmenu Specs](https://github.com/davatorium/rofi/wiki/dmenu_specs)
* [mode Specs](https://github.com/davatorium/rofi/wiki/mode-Specs)
* [F.A.Q.](https://github.com/davatorium/rofi/wiki/Frequently-Asked-Questions).
* [Script mode](https://github.com/davatorium/rofi/wiki/rfc-script-mode)
* [Debugging](https://github.com/davatorium/rofi/wiki/Debugging-Rofi)
* [Creating an issue](https://github.com/davatorium/rofi/blob/master/.github/CONTRIBUTING.md)
* [FORUM](https://reddit.com/r/qtools/)
* [Creating a Pull request](https://github.com/davatorium/rofi/wiki/Creating-a-pull-request)
# What is rofi not? # Discussion places:
Rofi is not: * [Reddit](https://reddit.com/r/qtools/)
* [GitHub Discussions](https://github.com/davatorium/rofi/discussions)
* A UI toolkit. * IRC (#rofi on irc.libera.chat)
* A library to be used in other applications.
* An application that can support every possible use-case. It tries to be generic enough to be usable by everybody.
* Specific functionality can be added using scripts or plugins, many exists.
* Just a dmenu replacement. The dmenu functionality is a nice 'extra' to **rofi**, not its main purpose.