py-singl-slider 1.0.7

A single virtual slider control

PySinglSlider

PySinglSlider is a customizable, simple single slider widget built with Pygame. Designed for quick setup and theming, it lets you add an interactive slider for Pygame applications that need fine-grained control over a value range.

Features

• Easily customizable for different themes and styles.
• Supports adjustable value ranges.
• Includes event listening for smooth handling of slider interactions.
• Simple integration into any Pygame-based project.

Installation

Install PySinglSlider via PyPI:

pip install py_singl_slider

Getting Started

Importing and Setting Up the Slider

To integrate PySinglSlider into your Pygame project, follow these steps:

1. Import PySinglSlider from py_singl_slider in your Pygame script. (see example down below)
2. Initialize the slider with optional parameters such as position, value range, initial value, and theme settings.
3. Handle events and render the slider in your game loop.

Example Usage

Here's a basic example to get started:

import pygame
import py_singl_slider

pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

# Create slider

slider = py_singl_slider.PySinglSlider(x=100, y=250, min_value=0, max_value=100, initial_value=50)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        # Pass events to the slider
        slider.listen_event(event)

    # Clear the screen
    screen.fill((255, 255, 255))
    
    # Render the slider
    slider.render(screen)
    
    # Display the current slider value
    font = pygame.font.Font(None, 36)
    value_text = font.render(f"Value: {slider.value:.2f}", True, (0, 0, 0))
    screen.blit(value_text, (100, 400))

    pygame.display.flip()
    clock.tick(30)

pygame.quit()

Parameters

• x (int): X-coordinate for slider position.
• y (int): Y-coordinate for slider position.
• min_value (int): Minimum value of the slider range.
• max_value (int): Maximum value of the slider range.
• initial_value (int): Starting value of the slider.
• theme_name (str): Name of the theme folder containing assets (images for handler, bar, etc.).
• theme_path (str, optional): Custom path to the theme directory if assets are not located in the default theme folder.

Documentation

Methods

load_image(image_name, theme_name, theme_folder_path=None)

Loads an image from the specified theme directory.

get_rect()

Returns the Pygame rectangle (Rect) of the slider bar.

listen_event(event)

Listens to and handles mouse or touch events for updating the slider’s handler position.

get_current_value()

Calculates and returns the slider's current value based on handler position.

render(screen)

Renders the slider's components (bar, handler) on the specified screen.

Asset Customization

To customize the slider's appearance, you can create new images for the slider's handler and bar components in a folder with your chosen theme_name. Place this folder in the theme directory or specify the path using theme_path.

Example Theme Folder Structure

project_root/
├── theme/
│   ├── default_theme/
│   │   ├── handler.png
│   │   ├── bar_center.png
│   │   ├── bar_corner.png
│   └── custom_theme/
│       ├── handler.png
│       ├── bar_center.png
│       ├── bar_corner.png
└── main.py

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Enjoy using PySinglSlider! Contributions, bug reports, and suggestions are welcome.