Wallman/README.org

118 lines
7 KiB
Org Mode
Raw Normal View History

2024-05-26 23:44:00 +02:00
#+TITLE: Readme
#+AUTHOR: Emma Nora Theuer
2024-05-27 02:42:42 +02:00
* Overwiev
2024-05-26 23:44:00 +02:00
** What is this?
2024-05-27 02:54:07 +02:00
This is my project wallman. Wallman is a simple python program used for setting Dynamic Wallpapers on minimalist X11 Window Managers and Wayland compositors. The name is a reference to TomSka: [[https://www.youtube.com/watch?v=k4Q3qD93rgI&t=131s]]
2024-05-27 02:42:42 +02:00
This version is an early Alpha. As of now, it supports the most important features for my usecase, those being randomly selected wallpaper sets and wallpaper sets that change by the time of day. The program is not modular yet and I would expect a lot of bugs related to the configuration file. Just how it is, I'm working on it.
As such, please make absolutely sure you follow the instructions on how to write the config file very closely. I will implement better config handling with more meaningful error output in the future. For now, follow everything really closely and read the logs if needed. If you do that, it /should/ work.
2024-05-26 23:44:00 +02:00
** What can it do?
2024-05-27 02:42:42 +02:00
Wallman currently has three main features:
+ Reading configuration details from a TOML file
2024-05-26 23:44:00 +02:00
+ Choosing from a set of Wallpapers and then setting the rest of the wallpapers accordingly
+ Settings Wallpapers at a specific time of the day
2024-09-01 20:00:01 +02:00
+ Be controlled via a systray
2024-05-26 23:44:00 +02:00
2024-05-27 02:42:42 +02:00
* Installation
** Depedencies
2024-05-28 22:43:16 +02:00
*** Always Required
2024-05-27 02:42:42 +02:00
+ Python 3.11 or newer (Required because of tomllib)
+ APScheduler (Install python-apscheduler or APScheduler, depending on the package manager)
+ feh (Used for setting the wallpapers, hard dependency)
*** Optional
+ libnotify (for desktop notification support)
2024-09-01 20:00:01 +02:00
+ pillow (For systray support)
+ pystray (For systray support)
*** Build dependencies
+ setuptools
+ build
** Installing with package Manager
2024-06-04 03:12:54 +02:00
*** Gentoo
2024-06-04 03:30:47 +02:00
This program, as of now, can be installed very easily on gentoo. Just follow these instructions:
2024-06-04 03:12:54 +02:00
#+BEGIN_SRC shell
git clone https://git.entheuer.de/emma/Wallman.git
2024-06-04 03:12:54 +02:00
doas eselect repository create wallman
doas cp -rf Wallman/distfiles/Gentoo/wallman /var/db/repos/
doas emerge -av wallman
#+END_SRC
A proper portage overlay will be created soon, so that updates can be handled automatically.
2024-06-04 03:12:54 +02:00
*** Arch Linux
2024-06-04 03:16:31 +02:00
Support for Arch Linux will be added soon.
2024-06-04 03:12:54 +02:00
*** Others
I will potentially write a version for nixpkgs and will also bundle wallman as a flatpak.
2024-05-26 23:44:00 +02:00
2024-06-04 03:16:31 +02:00
** Installing with pip
Wallman is available on PyPI. Simply run:
#+BEGIN_SRC shell
pip install wallman
#+END_SRC
** Installing manually
2024-09-01 20:00:01 +02:00
+ Install libnotify and feh from your package manager
2024-05-26 23:44:00 +02:00
#+BEGIN_SRC shell
2024-09-01 20:00:01 +02:00
pip install APScheduler pystray pillow
git clone https://git.entheuer.de/emma/Wallman.git
cd Wallman/
2024-09-02 13:25:50 +02:00
sudo mkdir -p /var/log/wallman
sudo chmod 733 /var/log/wallman
2024-05-27 02:42:42 +02:00
mkdir -p ~/.config/wallman
cp sample_config.toml ~/.config/wallman/wallman.toml
2024-09-02 13:25:50 +02:00
doas mkdir -p /etc/wallman/
cp -R icons/ /etc/wallman/
doas cp src/wallman.py /usr/bin/wallman
doas cp src/wallman_lib.py /usr/bin/wallman_lib.py
2024-09-02 13:25:50 +02:00
doas cp src/wallman_systray.py /usr/bin/wallman_systray.py
doas chmod +x /usr/bin/wallman
2024-05-26 23:44:00 +02:00
#+END_SRC
2024-05-28 22:43:16 +02:00
+ Edit the sample config
2024-05-26 23:44:00 +02:00
+ Profit
2024-05-27 02:42:42 +02:00
* Configuration
This is a short guide on how to correctly configure wallman. Look in the sample config for additional context.
** TOML Dictionaries
First of all, the config file is structured via different TOML dictionaries. There are two TOML dictionaries: general and changing_times that must be present in every config. Aside from that, further dictionaries are needed depending on how wallman is configured. You need to create a dictionary with the name of each wallpaper set defined in the used_sets list (more on that later). You should probably just configure wallman by editing the sample config as it is by far the easiest way to do it.
*** general
In general, you need to always define 3 variables and you can optionally add three more:
2024-05-28 22:53:20 +02:00
+ enable_wallpaper_sets: bool
2024-05-27 02:42:42 +02:00
A simple switch that states if you want to use different sets of wallpapers or not.
+ used_sets: list
A list that includes the names of the wallpaper sets you want to use. If you want to use only one, the list should have one entry.
+ wallpapers_per_set: int
The amount of wallpapers that you use in each set. It should be an integer.
+ Optional: notify: bool
This defaults to "false". Enable to set send a desktop notification when the wallpaper is changed. The program will still work correctly, even if this option is not defined at all.
2024-06-03 19:27:30 +02:00
+ Optional: fallback_wallpaper: bool
Wallpaper to be set if an error is found in the config or the wallpaper intended to be set cannot be found. Defaults to None. If none is set and the config has been written incorrectly, a ConfigError is raised and the program is exited. If an error in the config occurs but the fallback wallpaper has been defined, it will be set and wallman will exit with Code 1. If The config is written correctly but the wallpaper intended to be set can't be found, wallman will set the fallback wallpaper and continue to try setting future wallpapers.
+ Optional: loglevel: string
2024-09-02 13:25:50 +02:00
Loglevel to be used by wallman. Defaults to INFO. Choices MUST be DEBUG, INFO, WARNING, ERROR or CRITICAL. Using any capitalization is valid, all caps is reccomended. Wallman will crash if a value is specified that is not one of the specified ones.
2024-09-01 20:00:01 +02:00
+ Optional: systray: bool
This defaults to "true". This enables support for a systray that has the features to re-set your wallpaper (Mostly useful if feh shits itself or if you want to set the correct wallpaper for a specific time of day after your device was suspended) without rerolling the wallpaper set used, a button to reroll and then re-set the wallpaper, as well as a Quit button. Disable this to save a very tiny amount of memory.
2024-05-27 02:42:42 +02:00
*** changing_times
The changing_times dictionary is used to specify the times of the day when your wallpaper is switched. The names of the keys do not matter here, the values must always be strings in the "XX:YY:ZZ" 24 hour time system. use 00:00:00 for midnight. Note that XX should be in the range of 00-23 and YY and ZZ should be in the range of 00-59.
*** The other dictionaries
The other dictionaries must always have the names of the wallpaper sets from used_sets. If you have one wallpaper set, you need one additional dictionary, if you have two you need two etc. The standard config uses nature and anime, these names can be whatever you please as long as they are the same as the ones specified in used_sets.
The keys in the dictionary once again do not matter, the names of the keys in each dictionary must be strings and be absolute paths. They should not include spaces unless prefaced by a backslash.
* TODOs
** Structuring
+ Write unittests
2024-05-27 15:13:06 +02:00
+ Add documentation for developers
2024-05-27 02:42:42 +02:00
** Technical Details
2024-09-01 20:00:01 +02:00
+ Improve Modularity (Partially done)
2024-05-27 02:42:42 +02:00
+ Make the enabled flag in wallpaper_sets actually useful by making the used_sets field optional
+ Drop the feh dependecy and set wallpapers using pywlroots or python-xlib
** Features
+ Add support for wallpapers that dynamically change with the time of day (Morning, noon, evening, night or light levels) rather than to times set in the config
+ Add support for wallpapers that change by the weather
+ Add support for live wallpapers