README.md: Replace with info about fork

This commit is contained in:
Mihir Lad 2020-12-19 20:20:36 -05:00
parent 78475b7806
commit 56619b94a4
2 changed files with 212 additions and 152 deletions

364
README.md
View File

@ -1,160 +1,220 @@
<p align="center"> # polybar-dwm-module
<img src="banner.png" alt="Polybar"> ![DWM
</p> Module](https://github.com/mihirlad55/polybar-dwm-module/blob/master/dwm-module.png)
<p align="center"> **polybar-dwm-module** is a fork of
A fast and easy-to-use tool for creating status bars. [polybar](https://github.com/polybar/polybar) which implements a dwm module.
</p>
<p align="center">
<a href="https://github.com/polybar/polybar/releases"><img src="https://img.shields.io/github/release/polybar/polybar.svg"></a>
<a href="https://github.com/polybar/polybar/actions?query=workflow%3ACI"><img src="https://github.com/polybar/polybar/workflows/CI/badge.svg"></a>
<a href="https://github.com/polybar/polybar/actions?query=workflow%3A%22Release+Workflow%22"><img src="https://github.com/polybar/polybar/workflows/Release%20Workflow/badge.svg?branch=master"></a>
<a href="https://polybar.readthedocs.io"><img src="https://readthedocs.org/projects/polybar/badge/?version=latest"></a>
<a href="https://gitter.im/polybar/polybar"><img src="https://badges.gitter.im/polybar/polybar.svg"></a>
<a href="https://codecov.io/gh/polybar/polybar/branch/master"><img src="https://codecov.io/gh/polybar/polybar/branch/master/graph/badge.svg"></a>
<a href="https://github.com/polybar/polybar/blob/master/LICENSE"><img src="https://img.shields.io/github/license/polybar/polybar.svg"></a>
<a href="https://www.codetriage.com/polybar/polybar"><img src="https://www.codetriage.com/polybar/polybar/badges/users.svg"></a>
</p>
**Polybar** aims to help users build beautiful and highly customizable status bars
for their desktop environment, without the need of having a black belt in shell scripting.
Here are a few screenshots showing you what it can look like:
[![sample screenshot](https://i.imgur.com/xvlw9iHt.png)](https://i.imgur.com/xvlw9iH.png)
[![sample screenshot](https://i.imgur.com/cYQOuRrt.png)](https://i.imgur.com/cYQOuRr.png)
[![sample screenshot](https://i.imgur.com/A6spiZZt.png)](https://i.imgur.com/A6spiZZ.png)
[![sample screenshot](https://i.imgur.com/TY5a5r9t.png)](https://i.imgur.com/TY5a5r9.png)
You can find polybar configs for these example images (and other configs) [here](https://github.com/jaagr/dots/tree/master/.local/etc/themer/themes).
## Table of Contents
* [Introduction](#introduction)
* [Getting Help](#getting-help)
* [Contributing](#contributing)
* [Getting started](#getting-started)
* [Installation](#installation)
* [Configuration](#configuration)
* [Running](#running)
* [Community](#community)
* [Contributors](#contributors)
* [License](#license)
## Introduction ## Requirements
* dwm with the [IPC patch](https://github.com/mihirlad55/dwm-ipc) applied
* [dwmipcpp](https://github.com/mihirlad55/dwmipcpp) C++ client library for
communicating with dwm (included as a submodule).
* [jsoncpp](https://github.com/open-source-parsers/jsoncpp) for polybar and
dwmipcpp (required by module).
The main purpose of **Polybar** is to help users create awesome status bars. The [dwm-anybar patch](https://github.com/mihirlad55/dwm-anybar) is optionally
It has built-in functionality to display information about the most commonly used services. recommended for a better experience. This patch allows dwm to manage polybar and
Some of the services included so far: fixes some weird quirks that you may experience without it.
- Systray icons
- Window title
- Playback controls and status display for [MPD](https://www.musicpd.org/) using [libmpdclient](https://www.musicpd.org/libs/libmpdclient/)
- [ALSA](https://www.alsa-project.org/main/index.php/Main_Page) and [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) volume controls
- Workspace and desktop panel for [bspwm](https://github.com/baskerville/bspwm), [i3](https://github.com/i3/i3), and [dwm](https://dwm.suckless.org)
- Workspace module for [EWMH compliant](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html#idm140130320786080) window managers
- Keyboard layout and indicator status
- CPU and memory load indicator
- Battery display
- Network connection details
- Backlight level
- Date and time label
- Time-based shell script execution
- Command output tailing
- User-defined menu tree
- Inter-process messaging
- And more...
[See the wiki for more details](https://github.com/polybar/polybar/wiki).
## Getting Help
If you find yourself stuck, have a look at our [Support](SUPPORT.md) page for resources where you can find help.
## Contributing
Read our [contributing guidelines](CONTRIBUTING.md) for how to get started with contributing to polybar.
## Getting started
<a href="https://repology.org/metapackage/polybar">
<img src="https://repology.org/badge/vertical-allrepos/polybar.svg" alt="Packaging status" align="right">
</a>
Polybar was already packaged for the distros listed below.
If you can't find your distro here, you will have to [build from source](https://github.com/polybar/polybar/wiki/Compiling).
If you are using **Debian** (unstable or testing), you can install [polybar](https://tracker.debian.org/pkg/polybar) using `sudo apt install polybar`.
If you are using **Debian** (buster/stable), you need to enable [backports](https://wiki.debian.org/Backports) and then install using `sudo apt -t buster-backports install polybar`.
If you are using **Arch Linux**, you can install the AUR package [polybar-git](https://aur.archlinux.org/packages/polybar-git/) to get the latest version, or
[polybar](https://aur.archlinux.org/packages/polybar/) for the latest stable release.
If you are using **Void Linux**, you can install [polybar](https://github.com/void-linux/void-packages/blob/master/srcpkgs/polybar/template) using `xbps-install -S polybar`.
If you are using **NixOS**, polybar is available in both the stable and unstable channels and can be installed with the command `nix-env -iA nixos.polybar`.
If you are using **Slackware**, polybar is available from the [SlackBuilds](https://slackbuilds.org/repository/14.2/desktop/polybar/) repository.
If you are using **Source Mage GNU/Linux**, polybar spell is available in test grimoire and can be installed via `cast polybar`.
If you are using **openSUSE**, polybar is available from [OBS](https://build.opensuse.org/package/show/X11:Utilities/polybar/) repository. Package is available for openSUSE Leap 15.1, openSUSE Leap 15.2 and Tumbleweed.
If you are using **FreeBSD**, [polybar](https://svnweb.freebsd.org/ports/head/x11/polybar/) can be installed using `pkg install polybar`. Make sure you are using the `latest` package branch.
If you are using **Gentoo**, both release and git-master versions are available in the [main](https://packages.gentoo.org/packages/x11-misc/polybar) repository.
If you are using **Fedora**, you can install [polybar](https://src.fedoraproject.org/rpms/polybar) using `sudo dnf install polybar`.
### Installation
The [compiling page](https://github.com/polybar/polybar/wiki/Compiling) on the
wiki describes all steps necessary to build and install polybar.
### Configuration
Details on how to setup and configure the bar and each module have been moved to [the wiki](https://github.com/polybar/polybar/wiki/Configuration).
#### Install the example configuration
Run the following inside the build directory:
~~~ sh
$ make userconfig
~~~
Or you can copy the example config from `/usr/share/doc/polybar/config` or ` /usr/local/share/doc/polybar/config` (depending on your install parameters)
#### Launch the example bar
~~~ sh
$ polybar example
~~~
### Running
[See the wiki for details on how to run polybar](https://github.com/polybar/polybar/wiki).
## Community
Want to get in touch?
* Join our Gitter room at [gitter.im/polybar/polybar](https://gitter.im/polybar/polybar)
* We have our own subreddit at [r/polybar](https://www.reddit.com/r/polybar).
* Chat with us in the `#polybar` IRC channel on the `chat.freenode.net` server.
## Contributors
### Owner
* Michael Carlberg [**@jaagr**](https://github.com/jaagr/)
### Maintainers
* [**@NBonaparte**](https://github.com/NBonaparte)
* Chase Geigle [**@skystrife**](https://github.com/skystrife)
* Patrick Ziegler [**@patrick96**](https://github.com/patrick96)
### Logo Design by
* [**@Tobaloidee**](https://github.com/Tobaloidee)
### [All Contributors](https://github.com/polybar/polybar/graphs/contributors) ## The DWM Module
The dwm module currently supports the following:
- Labels:
* Display dwm tags
- Separator label between tags
* Display the current layout
* Display the currently focused window title (per monitor)
* Display label when focused window is floating
- Click Handlers:
* Tags:
- Left-click tag to view tag
- Right-click tag to toggle view on tag
- Scroll tags to view different tags (with wrapping, reverse scroll, and
empty tag scroll)
* Layout:
- Left-click to set `secondary-layout` (specified in config)
- Right-click to set previous layout
- Scroll to cycle through layouts (with wrapping and reverse scroll)
- Different formatting for different tag states:
* Focused: selected tag on selected monitor
* Unfocused: selected tag on unselected monitor
* Visible: unselected, but occupied tag on any monitor
* Urgent: Tag with window that has the urgent hint set
* Empty: Unselected and unoccupied tags
- The combined power of polybar
## How to Install
First, apply all the patches you want on dwm, saving the IPC patch for last.
Optionally, apply the [dwm-anybar
patch](https://github.com/mihirlad55/dwm-anybar) and make sure your `config.h`
contains the following
```
static const int showbar = 1; /* 0 means no bar */
static const int topbar = 1; /* 0 means bottom bar */
static const int usealtbar = 1; /* 1 means use non-dwm status bar */
static const char *altbarclass = "Polybar"; /* Alternate bar class name */
static const char *altbarcmd = "$HOME/bar.sh"; /* Alternate bar launch command */
```
If your polybar is to be displayed on the bottom of the monitor, set `topbar`
to `0`.
Next, apply the [IPC patch](https://github.com/mihirlad55/dwm-ipc). There will
likely be merge conflicts. The IPC patch is mostly additive, so in most conflict
cases, you will be keeping both changes.
After applying all your patches, make sure you compile and install dwm
```
$ sudo make install
```
Make sure you have `jsoncpp` installed, and any other requirements from
[polybar](https://github.com/polybar/polybar).
Arch linux users can install the
[`polybar-dwm-module`](https://aur.archlinux.org/packages/polybar-dwm-module/)
package from the AUR.
Otherwise you can clone, make, and install polybar yourself. Follow the on
screen prompts in the `build.sh` script and enable any additional features you
want.
```
$ git clone https://github.com/mihirlad55/polybar-dwm-module
$ cd polybar-dwm-module
$ ./build.sh -d
```
Configure the bar! You can view `/usr/share/doc/polybar/config` for a sample config that
includes the supported settings for the dwm module.
**IF YOU APPLIED THE ANYBAR PATCH**, make sure you have
`override-redirect = false` in your polybar config.
**IF YOU DID NOT APPLY THE ANYBAR PATCH**, make sure you have
`override-redirect = true` in your polybar config. You will have to set the bar
height in your dwm's `config.h` to match polybar's height and make sure
`showbar` is set to `1` in your `config.h`. Also make sure `topbar` is set to
the correct value based on if your polybar is a bottom/top bar.
## Launching Polybar
There are multiple ways to launch polybar. Whatever way you decide to use, make
sure polybar launches a few seconds after dwm, else dwm's socket will not be
initialized and the module will fail:
### Anybar Method
The `altbarcmd` variable can be set to the bar launch script. When you apply the
anybar patch, make sure `spawnbar()` occurs in the `setup()` function after
`setupepoll()` and this will ensure that the bar is launched after dwm is ready.
Also make sure that the script checks for running bars before launching more,
else if dwm is restarted, duplicate bars will be launched.
### Hacky Delay Method
In your `.xsession` script or whatever script launches at startup, add something
like the following:
```
$(sleep 4s && "$HOME/launch-polybar.sh") &
```
This will start your polybar script after a 4 second delay which should give dwm
enough time to initialize before polybar tries to connect to dwm. If this
doesn't work, try a longer delay.
### Autostart Method
Apply the [autostart patch](https://dwm.suckless.org/patches/autostart/). In
your `autostart_blocking.sh`, add your command to launch polybar.
## Sample Module Configuration
```ini
...
modules-left = ... dwm ...
...
[module/dwm]
type = internal/dwm
format = <label-tags> <label-layout> <label-floating> <label-title>
; Path to dwm socket (default: /tmp/dwm.sock)
; socket-path = /tmp/dwm.sock
; Left-click to view tag, right-click to toggle tag view
enable-tags-click = false
; Scroll to cycle between available tags
enable-tags-scroll = false
; If true and enable-tags-scroll = true, scrolling will view all tags regardless if occupied
tags-scroll-empty = false
; If true and enable-tags-scroll = true, scrolling will cycle through tags backwards
tags-scroll-reverse = false
; If true and enable-tags-scroll = true, wrap active tag when scrolling
tags-scroll-wrap = false
; Left-click to set secondary layout, right-click to switch to previous layout
enable-layout-click = false
; Scroll to cycle between available layouts
enable-layout-scroll = false
; Wrap when scrolling and reaching beginning/end of layouts
layout-scroll-wrap = false
; Reverse scroll direction
layout-scroll-reverse = false
; If enable-layout-click = true, clicking the layout symbol will switch to this layout
secondary-layout-symbol = [M]
; Separator in between shown tags
; label-separator = |
; Title of currently focused window
; Available tokens:
; %title%
label-title = %title%
label-title-padding = 2
label-title-foreground = ${colors.primary}
label-title-maxlen = 30
; Symbol of current layout
; Available tokens:
; %symbol%
label-layout = %symbol%
label-layout-padding = 2
label-layout-foreground = #000
label-layout-background = ${colors.primary}
; Text to show when currently focused window is floating
label-floating = F
; States: focused, unfocused, visible, urgent, empty
; Available tokens:
; %name%
; focused = Selected tag on focused monitor
label-focused = %name%
label-focused-background = ${colors.background-alt}
label-focused-underline= ${colors.primary}
label-focused-padding = 2
; unfocused = Unselected tag on unselected monitor
label-unfocused = %name%
label-unfocused-padding = 2
; visible = Unselected tag, but occupied tag on any monitor
label-visible = %name%
label-visible-background = ${self.label-focused-background}
label-visible-underline = ${self.label-focused-underline}
label-visible-padding = ${self.label-focused-padding}
; urgent = Unselected tag with window that has urgency hint set
label-urgent = %name%
label-urgent-background = ${colors.alert}
label-urgent-padding = 2
; empty = Unselected and unoccupied tag
; This can be set to an empty string to hide empty tags
label-empty = %name%
label-empty-background = ${colors.primary}
label-empty-padding = 2
```
## License ## License
Polybar is licensed under the MIT license. [See LICENSE for more
Polybar is licensed under the MIT license. [See LICENSE for more information](https://github.com/polybar/polybar/blob/master/LICENSE). information](https://github.com/polybar/polybar/blob/master/LICENSE).

BIN
dwm-module.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.3 KiB