Path: /ui_components/ui_image.py
UIImage is a QLabel subclass that displays a media image scaled to fit its parent widget while maintaining aspect ratio and configurable horizontal padding.
Use UIImage to embed static images (e.g., logos, backgrounds) in your application's UI, automatically resizing them on parent widget changes.
Ideal for full-screen overlays or dialogs where images must adapt to varying window sizes without distortion.
PyQt5.QtWidgets.QLabel, PyQt5.QtCore.Qt, PyQt5.QtGui.QPixmap, and PyQt5.QEvent
Raven Development Team utility modules: util_load_font.load_font, util_error_popup.show_error_popup
| Parameter | Type | Description | Default |
|---|---|---|---|
| filename | string | Name of the image file located in the media directory | — |
| parent | QWidget | Parent widget used to size and display the image | None |
| horizontal_buffer | float | Fractional padding on each side of the image (0.0 ≤ buffer < 0.5) | 0.3 |
image_widget = UIImage("logo.png", parent=main_window, horizontal_buffer=0.2)On initialization, UIImage loads the specified font, validates horizontal_buffer, determines the base path (accounting for frozen executables), and constructs the image path in the media directory. It then loads the image as a QPixmap, shows an error popup on failure, and installs an event filter on the parent to listen for resize events. The _update_pixmap method calculates available width and height based on the buffer, scales the original pixmap with aspect ratio preserved, and updates the QLabel display.
Invalid horizontal_buffer values or missing image files trigger show_error_popup dialogs, halting further setup. No silent failures occur, ensuring developers are notified immediately of configuration issues.
Filenames are used directly to build filesystem paths; inputs should be restricted to valid media filenames to prevent directory traversal. All image loading occurs from the trusted media directory.
This component uses error popups for exceptions but does not emit log entries by default. Integrate with the application's logging framework if persistent error records are required.
Unit tests can instantiate UIImage with a QMainWindow parent, verify correct geometry and pixmap scaling via QTest, and assert error popups for invalid buffers or missing files. Manual testing involves resizing the parent widget and confirming the image updates appropriately.
Author: Raven Development Team