Metadata-Version: 2.4
Name: wselector
Version: 0.2.0
Summary: A modern GTK4/Adwaita application for browsing, downloading, and setting wallpapers from Wallhaven.cc
Home-page: https://github.com/Cookiiieee/WSelector
Author: Cookiiieee
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyGObject>=3.42.0
Requires-Dist: requests>=2.31.0
Requires-Dist: beautifulsoup4>=4.13.4
Requires-Dist: psutil>=7.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# WSelector

<div align="center">
  <img src="https://raw.githubusercontent.com/Cookiiieee/WSelector/main/data/icons/hicolor/512x512/apps/io.github.Cookiiieee.WSelector.png" width="128" height="128" alt="WSelector Icon">
</div>

<div align="center">
A modern GTK4/Adwaita application for browsing, downloading, and setting wallpapers from Wallhaven.cc website.
</div>

##  Screenshot

<div align="center">
   <img src="https://raw.githubusercontent.com/Cookiiieee/WSelector/main/screenshots/main.png">
</div>

## ✨ Features

### Wallpaper Browsing
- Browse high-quality wallpapers from Wallhaven.cc
- Smooth infinite scrolling for seamless browsing
- Search functionality with debounce mechanism
- Filter by categories (General, Anime, People)
- Set purity levels (SFW, Sketchy)
- Sort by latest, popular, random
- Drag-to-pan functionality in preview mode
- Responsive image scaling and positioning

### Wallpaper Management
- Preview wallpapers
- One-click download and set as wallpaper
- View and manage downloaded wallpapers
- Automatic organization in `~/Pictures/WSelector/`

### User Experience
- Clean, modern GTK4/Adwaita interface
- Dark/Light theme support with system preference detection
- Toast notifications with action buttons
- Responsive design for all screen sizes
- Smooth animations and transitions
- Intuitive drag gestures for image navigation

## 🖥️ System Requirements

- Linux with Wayland or X11
- GTK 4.10 or later
- Python 3.12 (included in GNOME 48 runtime)
- Flatpak with Flathub repository configured
- Internet connection for wallpaper downloads

## 📦 Install from Flathub

1. Manual Install:
   ```bash
   flatpak install flathub io.github.Cookiiieee.WSelector
   ```

2. Run the flatpak:
   ```bash
   flatpak run io.github.Cookiiieee.WSelector
   ```

## 🚀 Build from Source

1. Install prerequisites:
   ```bash
   # On Ubuntu/Debian
   sudo apt install flatpak flatpak-builder
   flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
   flatpak install flathub org.gnome.Sdk//48 org.gnome.Platform//48
   ```

2. Clone the repository and build:
   ```bash
   git clone https://github.com/Cookiiieee/WSelector.git
   cd WSelector
   flatpak-builder --user --install --force-clean build-dir io.github.Cookiiieee.WSelector.json
   ```

3. Run the application:
   ```bash
   flatpak run io.github.Cookiiieee.WSelector
   ```

### Permissions

The application requests the following permissions for full functionality:

- `--filesystem=home`: Required for:
  - Creating and executing temporary scripts to set wallpapers
  - Accessing configuration files
  - Creating necessary directories
  
- `--filesystem=xdg-pictures:create`: For saving wallpapers to `~/Pictures/WSelector/`

- Network access: Required to fetch wallpapers from Wallhaven.cc

- Wayland/X11 sockets: For proper display integration

## 📂 File Locations

- **Configuration**: `~/.var/app/io.github.Cookiiieee.WSelector/config/wselector/config.json`
- **Cache**: `~/.cache/wselector/` (thumbnails and temporary files)
- **Downloads**: `~/Pictures/WSelector/` (all downloaded wallpapers)
- **Logs**: `~/.var/app/io.github.Cookiiieee.WSelector/data/wselector/logs/` (debug information)

## 🔧 Troubleshooting

### Wallpaper Setting Issues
If wallpapers aren't setting correctly:
1. Ensure the application has the necessary permissions
2. Check that your desktop environment is supported (GNOME, KDE, XFCE, etc.)
3. Verify that the wallpaper directory exists and is writable
4. For Wayland users: Ensure `xdg-desktop-portal` is installed and running

### Performance Issues
If you experience any lag or stuttering:
1. Try reducing the number of concurrent downloads
2. Clear the thumbnail cache in `~/.cache/wselector/`
3. Restart the application to free up system resources

### Network Issues
If you encounter API errors:
1. Check your internet connection
2. Verify that Wallhaven.cc is accessible
3. The application implements retry logic for failed requests

## 🎯 Tips & Tricks

- Use the mouse wheel to quickly scroll through wallpapers in preview mode
- Right-click on any wallpaper to access quick actions
- Press `Esc` to close the preview window
- The application automatically saves your search preferences and last viewed position

## 📄 License

This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Wallhaven.cc](https://wallhaven.cc) for their amazing wallpaper collection.

[![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=cookiiieee&button_colour=5F7FFF&font_colour=ffffff&font_family=Poppins&outline_colour=000000&coffee_colour=FFDD00&font_size=14&height=28&width=150)](https://www.buymeacoffee.com/cookiiieee)
