A text scroller for panels or terminals





GitHub Stars



Last Commit

1mo ago










  • Zscroll [[https://github.com/noctuid/zscroll/actions/workflows/test.yml][https://github.com/noctuid/zscroll/actions/workflows/test.yml/badge.svg]] [[https://codecov.io/github/noctuid/zscroll?branch=master][https://codecov.io/github/noctuid/zscroll/coverage.svg?branch=master]] [[https://github.com/ambv/black][https://img.shields.io/badge/code%20style-black-000000.svg]]

The most common use cases are described in this README. For complete information on every flag, please see the man page (or the help text for basic information on every flag).

** Version 2.0 Breaking Changes

  • Long options are now hyphenated (e.g. =--update-check=)
  • All boolean options take an argument (e.g. =--scroll false=)
  • Newlines will be used by default (=--newline= defaults to true) as zscroll's primary use case is for panels, and this behavior is necessary for scrolling to work with polybar and lemonbar.
  • =-m= / =-M= syntax has changed to eliminate the previous complicated rules
  • The =-f= and =-c= flags have been removed. I don't see them as having a legitimate use case (the default behavior for handling fullwidth characters is much saner), but if anyone would like them back, feel free to make an issue. =-c= would count fullwidth characters as length 1, causing the scrolling text length to change. =-f= would convert all letters to fullwidth if any fullwidth letters were found.

** Simple Example Scroll the currently playing mpd song: #+begin_src sh $ zscroll -b "⮕ " "$(mpc current)"


$ mpc current | zscroll -b "⮕ " #+end_src

By default, zscroll will add " - " between the end and start of scrolling text. This can be adjusted with the ~-p~ option. Here is a zoomed in example of the above command (with a 0.4 second update delay):


Installation * Arch Install [[https://aur.archlinux.org/packages/zscroll-git/][zscroll-git]] from the AUR.

*** Nix [[https://nixos.org/nix/][Nix]] is a distro-independent package manager.

#+begin_src sh $ nix-env -i zscroll #+end_src

** Manual #+begin_src sh $ git clone https://github.com/noctuid/zscroll $ cd zscroll $ sudo python3 setup.py install #+end_src This program will not work with Python 2. For this reason you must* install with Python 3. This can be done in Ubuntu with =sudo python3 setup.py install= and may be the same for other distributions. If this does not work for you, please consult your distribution's documentation.

/Note: [[https://github.com/asdf-vm/asdf][asdf]] users might have to run/ ~asdf reshim~ /command before using/ ~zscroll~.

** Dynamically Updating Text Zscroll can now update its text by itself. This may be nice for panels that don't allow for the user to conditionally start new processes. It also simplifies the logic necessary to change settings for the scrolling text and gets rid of the need for an [[https://github.com/noctuid/dotfiles/blob/a251c682aa71e115ca83e75f938016e2f134ed47/aesthetics/.panel_scripts/panel#L39][ugly function]] to repeatedly kill and start the scroller.

A simple use case is where one might want to display the current window's title. This can be done with the ~-u~ option, which will run zscroll's positional argument as a shell command to check for changes: #+begin_src sh zscroll -b "| " -a " |" -u true "xtitle" #+end_src

Zscroll even supports more complex updates by searching for a regular expression in the output of a command to determine whether certain settings should be changed. As an example, this can be useful for displaying a pause icon and prevent scrolling when the current song is paused. The following command will take these actions when "paused" is found in the output of the shell command ~mpc status~: #+begin_src sh zscroll --before-text "♪ x" --delay 0.3 \ --match-command "mpc status" \ --match-text "playing" "--before-text ' '" \ --match-text "paused" "--before-text ' ' --scroll 0" \ --update-check true "mpc current"

or shortopts

zscroll -b "♪ x" -d 0.3 \ -M "mpc status" \ -m "playing" "-b ' '" \ -m "paused" "-b ' ' -s 0" \ -u t "mpc current" #+end_src

New options (and possibly new scroll-text) should be specified as the second argument to every =-m=. Options not specified with an =-m= will default to the user-specified values outside of the =-m= (or the base defaults). Any option can be altered when a ~-m~ search term is found (except for =-m= and =-M=, which will be ignored). Note that when multiple ~-m~ options happen to be matched, it is the last one that will take effect.

See the man page for more information.

** Fullwidth Characters Zscroll intelligently deals with fullwidth characters by default by counting them as twice the length of halfwidth characters (and phasing them in and out in two steps). This ensures that the actual visual length and speed of the scrolling text does not change. Here is a normal-sized gif of the above command that demonstrates this:


** Use with Polybar Here's an example of using zscroll instead of polybar's mpd module.

In polybar config: #+begin_src conf [module/mpd] type = custom/script exec = /path/to/script tail = true

label-foreground = ${colors.music} #+end_src

In the script: #+begin_src shell #!/usr/bin/env bash

zscroll --before-text "♪ x" --delay 0.3 \ --match-command "mpc status" \ --match-text "playing" "--before-text ' '" \ --match-text "paused" "--before-text ' ' --scroll 0" \ --update-check true "mpc current" &

wait #+end_src

For an alternate method that does not use zscroll's dynamic updating, see [[https://github.com/jaagr/polybar/issues/353#issuecomment-273388042][here]].

** Similar

  • z3bratabs' [[https://github.com/z3bratabs/skroll][skroll]]
  • benghaem's [[https://github.com/benghaem/dotfiles/blob/1dcbee5ed235a8e319dcc4255df10f0a6b23b6fe/bin/panel/scroller.c][scroller]]

** Why I was using benghaem's scroller for a while. I didn't like that the arguments were all positional, the lack of a right text padding option, and the lack of an option to change the scroll speed. I found skroll afterwards which is nicer since it has options and an actual man page and is in the AUR. However, it doesn't have a left text padding option which was necessary for my bar script to work properly. Also, they are both written in C, which doesn't seem practical to me for such a simple script and is the main reason I created zscroll instead of contributing.

Zscroll supports the features I liked from each. It has a speed option, adds an option for right padding text, will work on text as an argument or piped into it, handles fullwidth characters intelligently, and has other advanced features.

I called this zscroll because it's the last scroller I'll use... but more importantly because I couldn't think of another name.

** Contributing Zscroll is using [[https://black.readthedocs.io/en/stable/][black]] and [[https://pycqa.github.io/isort/][isort]] for automatic formatting and import sorting. [[http://flake8.pycqa.org/en/latest/][flake8]] and [[https://www.pylint.org/][pylint]], and [[http://www.pydocstyle.org/en/stable/][pydocstyle]] are used for linting. [[https://docs.pytest.org/en/latest/][pytest]] is used for testing.

Development dependencies can be installed with ~make deps~ or ~poetry installed~ ([[https://python-poetry.org/][poetry]] must be installed first). If you want to make a PR, please write tests for any added or fixed functionality and make sure that the code passes ~make lint~ and ~make test~.

To automatically format with black when committing and abort the commit if there are any flake8 errors, you can install [[https://pre-commit.com/][pre-commit]] and run =pre-commit install= once in the repository root after cloning.

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0