#+title: README
#+author: Étienne Pflieger

Chwall [[https://en.wiktionary.org/wiki/Appendix:French_pronunciation][{ʃwal}]] is tiny automatic wallpaper changer for your Linux
desktop, written in python.

It's name is the contraction of /change wallpaper/, which may be
pronounced as a twisted version of /cheval/, which means /horse/ in
french.

* Goal and features

Easily change your wallpaper from time to time, benefiting from various
online sources and your own wallpapers collections.

Chwall is currently able to retrieve pictures from the following
sources:

- your local folders
- Bing pictures of the day
- NASA astronomical pictures of the day
- Deviantart RSS feeds
- Unsplash (requires a free API key)
- Pexels (requires a free API key)
- Muzei
- Reddit
- Smashing Magazine monthly wallpaper collection
- WikiArt
- Wallhaven

It currently supports some major desktop environments (Gnome, XFCE,
Mate, KDE Plasma), Sway and anything accepting feh.

* Install

You must have previously installed GTK gi python library. This is very
often already packaged for your distribution, in ~python-gobject~ on
Archlinux or ~python3-gi~ for Debian based distributions.

#+begin_src shell
sudo make install
#+end_src

There is also two AUR packages for archlinux:
- [[https://aur.archlinux.org/packages/chwall][chwall]] (stable version)
- [[https://aur.archlinux.org/packages/chwall-git][chwall-git]] (unstable version)

* Usage

Chwall is organized around 5 components:

- chwall-app
- chwall-icon
- chwall-indicator
- chwall
- chwall-daemon

The ~chwall-app~, ~chwall-icon~ and ~chwall-indicator~ are alternative
graphical interface to the simple ~chwall~ command line client. These 3
programs are here to drive the ~chwall-daemon~ component, which is
responsible to change the wallpaper at given interval of time.

After a system-wide installation, you should find a icon among your
other programs, which starts ~chwall-app~. From there, you'll be able to
access the preferences window to customize the behavior of chwall.

You can also interact with the daemon through the system tray icon
~chwall-icon~, which also let you customize Chwall with the preferences
window. ~chwall-indicator~ is also available as a more modern tray icon
alternative (~chwall-icon~ does not work under wayland).

In the case, where you want a totally headless experience, you should
try the simple ~chwall~ command line client. If you don't want (or
cannot) use the preferences window, you should read the [[./CONFIG.org][configuration
help]] document to know more about the chwall config file.

* Contributing

** Translations

You can fetch the gettext files directly from the source code tree and
send your changes as a pull request (see bellow) or by email, as you
prefer.

** Code

The canonical repository is located at
[[https://git.umaneti.net/chwall]]. Mirror exists on [[https://framagit.org/milouse/chwall][Framagit]] and on [[https://github.com/milouse/chwall][Github]].

Merge request and issues are accepted on all mirrors or by mail to the
main author.

** About Generative Artificial Intelligence

This project began as a one-person hobby, who really like to think about
how to do thing. To the contrary, reading long and synthetic prose or
reviewing stuff generated by some machinery is not part of their
taste. It is not expected to change any time soon, thus if you plan to
contribute, please take care to make a human contribution.

We prefer ugly, incomplete, but warm and involved contribution, over
whatever artificial tool might do for you. If you don’t know how to
write code, this is not a problem: feature requests will always be
welcome, and again, contributors will love help you to address your
ideas.

** Code of conduct

#+html: <img alt="Contributor Covenant" src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg"/>

Chwall is proudly following the [[https://www.contributor-covenant.org/][Contributor Covenant Code of
Conduct]]. You can read it here:

[[./CODE_OF_CONDUCT.org][Code of Conduct]]


** Support

#+html: <a href="https://liberapay.com/milouse/donate"><img alt="Support using Liberapay" src="https://img.shields.io/badge/Liberapay-Support_me-yellow?logo=liberapay"/></a>
#+html: <a href="https://paypal.me/milouse"><img alt="Support using Paypal" src="https://img.shields.io/badge/Paypal-Support_me-00457C?logo=paypal&labelColor=lightgray"/></a>

You can help me a lot by giving me some tip, either through [[https://liberapay.com/milouse][Liberapay]] or
[[https://paypal.me/milouse][Paypal]]. Thank you very much!

* Credits

The icon is resized [[https://openclipart.org/detail/21282/waved-horse-spring-version-2009][from the work of Bernd Wachtmeister (Touchstone)]].