Scrolling

ImageViewer

Lets people zoom around the pointer and pan a single image, with fit and actual-size views.

Example

Usage

Pan and zoom an image

The wheel, a pinch or Ctrl/Command + wheel zooms around the pointer, dragging pans, and the toolbar appears on hover.

#include <FluentQt/Scrolling.h>
using namespace fluent::scrolling;

auto* viewer = new ImageViewer(this);
viewer->setMaximumWidth(460);
viewer->setFixedHeight(290);
viewer->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Fixed);
viewer->setAccessibleName(QStringLiteral("Harbor at dusk"));
viewer->setPixmap(imageViewerScene(QSize(1600, 1000), 0));

// Double-click toggles 100%; after focus, + - 0 1 and the
// arrow keys zoom, reset and pan.
auto updateStatus = [viewer, status] {
    status->setText(imageViewerStatusText(viewer));
};
connect(viewer, &ImageViewer::zoomFactorChanged, status, updateStatus);
connect(viewer, &ImageViewer::fitModeChanged, status, updateStatus);

import fluentqt

from PySide6.QtCore import QSize
from PySide6.QtWidgets import QSizePolicy

viewer = fluentqt.ImageViewer()
viewer.setMaximumWidth(460)
viewer.setFixedHeight(290)
viewer.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)
viewer.setAccessibleName('Harbor at dusk')
viewer.setPixmap(image_viewer_scene(QSize(1600, 1000), 0))
def update_status(*_args):
    status.setText(image_viewer_status_text(viewer))
viewer.zoomFactorChanged.connect(update_status)
viewer.fitModeChanged.connect(update_status)

API

Declaration

`fluent::scrolling::ImageViewer`

Inherits QWidget · FluentElement · QMLPlus

Pan-and-zoom viewer for a single image.

Constructors

explicit ImageViewer(QWidget* parent = nullptr)

Properties

QPixmap pixmap: Image shown by the viewer; setting a new one resets the view.
Read pixmap()Write setPixmap()Notify pixmapChanged()
qreal zoomFactor: Current zoom factor; 1.0 is the image's device-independent size.
Read zoomFactor()Write setZoomFactor()Notify zoomFactorChanged()
qreal minZoomFactor: Smallest zoom factor; the fit factor stays reachable below it.
Read minZoomFactor()Write setMinZoomFactor()Notify minZoomFactorChanged()
qreal maxZoomFactor: Largest zoom factor; the fit factor stays reachable above it.
Read maxZoomFactor()Write setMaxZoomFactor()Notify maxZoomFactorChanged()
QPointF viewCenter: Image point, in device-independent image pixels, shown at the viewport center.
Read viewCenter()Write setViewCenter()Notify viewCenterChanged()
FitMode fitMode: Whether the view follows a fit rule when the viewport resizes.
Read fitMode()Write setFitMode()Notify fitModeChanged()
WheelAction wheelAction: What an unmodified mouse wheel does.
Read wheelAction()Write setWheelAction()Notify wheelActionChanged()
ControlsVisibility controlsVisibility: Visibility policy of the built-in zoom controls.
Read controlsVisibility()Write setControlsVisibility()Notify controlsVisibilityChanged()
bool zoomIndicatorEnabled: Whether direct zoom input briefly shows the zoom percentage when the controls are hidden.
Read isZoomIndicatorEnabled()Write setZoomIndicatorEnabled()Notify zoomIndicatorEnabledChanged()
bool frameVisible: Whether the viewer paints its rounded background and border.
Read isFrameVisible()Write setFrameVisible()Notify frameVisibleChanged()
Qt::TransformationMode transformationMode: Sampling used to scale the image; Fast keeps individual pixels sharp.
Read transformationMode()Write setTransformationMode()Notify transformationModeChanged()

Methods

QPixmap pixmap() const: Image shown by the viewer; setting a new one resets the view.
void setPixmap(const QPixmap& pixmap): Image shown by the viewer; setting a new one resets the view.
void setImage(const QImage& image): Converts an image to a pixmap and shows it.
QSizeF imageSize() const: Returns the image's device-independent size, or an empty size without an image.
qreal fitZoomFactor() const: Returns the factor that fits the whole image into the current viewport.
qreal zoomFactor() const: Current zoom factor; 1.0 is the image's device-independent size.
void setZoomFactor(qreal factor): Current zoom factor; 1.0 is the image's device-independent size.
qreal minZoomFactor() const: Smallest zoom factor; the fit factor stays reachable below it.
void setMinZoomFactor(qreal factor): Smallest zoom factor; the fit factor stays reachable below it.
qreal maxZoomFactor() const: Largest zoom factor; the fit factor stays reachable above it.
void setMaxZoomFactor(qreal factor): Largest zoom factor; the fit factor stays reachable above it.
QPointF viewCenter() const: Image point, in device-independent image pixels, shown at the viewport center.
void setViewCenter(const QPointF& center): Image point, in device-independent image pixels, shown at the viewport center.
FitMode fitMode() const: Whether the view follows a fit rule when the viewport resizes.
void setFitMode(FitMode mode): Whether the view follows a fit rule when the viewport resizes.
WheelAction wheelAction() const: What an unmodified mouse wheel does.
void setWheelAction(WheelAction action): What an unmodified mouse wheel does.
ControlsVisibility controlsVisibility() const: Visibility policy of the built-in zoom controls.
void setControlsVisibility(ControlsVisibility visibility): Visibility policy of the built-in zoom controls.
bool isZoomIndicatorEnabled() const: Whether direct zoom input briefly shows the zoom percentage when the controls are hidden.
void setZoomIndicatorEnabled(bool enabled): Whether direct zoom input briefly shows the zoom percentage when the controls are hidden.
bool isFrameVisible() const: Whether the viewer paints its rounded background and border.
void setFrameVisible(bool visible): Whether the viewer paints its rounded background and border.
Qt::TransformationMode transformationMode() const: Sampling used to scale the image; Fast keeps individual pixels sharp.
void setTransformationMode(Qt::TransformationMode mode): Sampling used to scale the image; Fast keeps individual pixels sharp.
void zoomIn(bool animated = false): Zooms in to the next preset step around the viewport center.
void zoomOut(bool animated = false): Zooms out to the previous preset step around the viewport center.
void zoomTo(qreal factor, bool animated = false): Zooms to a factor around the viewport center.
void zoomTo(qreal factor, const QPointF& viewportAnchor, bool animated = false): Zooms to a factor while keeping the image point under a viewport position fixed.
void zoomToActualSize(bool animated = false): Shows the image at 100% around the viewport center.
void fitToView(bool animated = false): Fits the whole image into the viewport and keeps fitting on resize.
void resetView(bool animated = false): Returns to the initial view: large images fit, small images stay at 100%.
void panBy(qreal dx, qreal dy): Moves the visible region by viewport pixels; positive values reveal the right and bottom.
QPointF mapToImage(const QPointF& viewportPoint) const: Maps a viewport position to device-independent image coordinates.
QPointF mapFromImage(const QPointF& imagePoint) const: Maps device-independent image coordinates to a viewport position.
QSize sizeHint() const override
QSize minimumSizeHint() const override

Signals

void pixmapChanged(): Image shown by the viewer; setting a new one resets the view.
void zoomFactorChanged(qreal factor): Current zoom factor; 1.0 is the image's device-independent size.
void minZoomFactorChanged(qreal factor): Smallest zoom factor; the fit factor stays reachable below it.
void maxZoomFactorChanged(qreal factor): Largest zoom factor; the fit factor stays reachable above it.
void viewCenterChanged(const QPointF& center): Image point, in device-independent image pixels, shown at the viewport center.
void fitModeChanged(fluent::scrolling::ImageViewer::FitMode mode): Whether the view follows a fit rule when the viewport resizes.
void wheelActionChanged(fluent::scrolling::ImageViewer::WheelAction action): What an unmodified mouse wheel does.
void controlsVisibilityChanged(fluent::scrolling::ImageViewer::ControlsVisibility visibility): Visibility policy of the built-in zoom controls.
void zoomIndicatorEnabledChanged(bool enabled): Whether direct zoom input briefly shows the zoom percentage when the controls are hidden.
void frameVisibleChanged(bool visible): Whether the viewer paints its rounded background and border.
void transformationModeChanged(Qt::TransformationMode mode): Sampling used to scale the image; Fast keeps individual pixels sharp.

Enumerations

enum class FitMode: Fit rule followed by the view.
Manual Keeps the zoom factor and view center.
Contain Fits the whole image, enlarging small images.
ScaleDown Fits large images and keeps small ones at 100%.
enum class WheelAction: Action of an unmodified mouse wheel.
Zoom Zooms around the pointer.
Pan Pans, or passes the wheel to the parent without range.
enum class ControlsVisibility: Visibility policy of the zoom controls.
Hidden Never shown.
Auto Shown while hovered, focused or dragged.
Visible Always shown while an image is set.