Implementing DPI Awareness in Custom Widgets

Modern desktop application development demands robust support for high-resolution displays. Ensuring consistent visual fidelity across standard 1080p monitors and 4K screens is critical for user experience. This guide details the architectural approach to adapting custom Qt widgets, specifically focusing on pie charts, within a high DPI framework.

Framework Architecture for Scaling

Effective DPI adaptation relies on managing two primary dimensions: physical geometry and typography. The framework must abstract the scaling logic so that developers can define layouts in logical units while the system renders them appropriately for the target device pixel ratio.

Physical Geometry Management

Physical dimensions encompass not only the main window but also all child widgets and the spacing between them. To facilitate seamless integration, base interface classes are extended to override size-related methods. This allows the framework to intercept dimension settings and apply the necessary scaling factor before passing values to the underlying Qt APIs.

Simply multiplying dimensions by a scale factor is insufficient if the application moves between monitors with different DPI settings. Re-calling every setter method manually is impractical. Instead, the framework maintains a layout tree structure. By recording the hierarchical relationships during the initial layout pass, the system can recursively apply scaling transformations to all components when the DPI context changes, ensuring smooth transitions without visual jumps.

Typography and Stylesheets

Font scaling is handled automatically for standard controls via the framework. The system maintains stylesheet configurations for common scaling factors (1x, 2x, 3x). If the current device ratio falls between these values (e.g., 1.8x), the framework dynamically generates a temporary stylesheet based on the nearest configuration. Font sizes are adjusted proportionally, ensuring legibility across different densities.

Custom Painting Considerations

While standard widgets benefit from automatic scaling, custom-painted interfaces require manual intervention. Developers must explicitly account for the scaling factor when drawing text and images.

Text Rendering

When rendering text, the scaling factor is calculated as Current DPI / 96.0. A font defined as 12px at 96 DPI must be rendered at 24px on a 192 DPI display. Additionally, bounding rectangles used for text clipping must also be scaled. Failing to expand the drawing region while increasing font size will result in clipped or truncated text.

Image Assets

Bitmap assets must be loaded at the appropriate resolution to avoid blurriness. The following utility function demonstrates how to retrieve and scale images based on the current device ratio. It leverages Qt's internal pixmap caching to optimize performance.

QPixmap AssetLoader::fetchScaledImage(const QString &sourcePath, qreal deviceRatio)
{
    // Resolve the path based on the nearest integer scale factor
    QString resolvedPath = AssetLoader::resolveResourcePath(sourcePath, qRound(deviceRatio));
    
    // Calculate the precise scaling factor needed
    qreal scalingFactor = AssetLoader::calculateScaleRatio(deviceRatio);
    
    QPixmap pixmap(resolvedPath);
    
    // Only scale if the factor deviates from unity
    if (scalingFactor != 1.0)
    {
        pixmap = pixmap.scaled(pixmap.size() * scalingFactor, Qt::IgnoreAspectRatio, Qt::SmoothTransformation);
    }

    return pixmap;
}

Pie Chart Geometry Adaptation

Custom charts, such as pie charts, rely heavily on geometric calculations for sectors, legends, and labels. On high DPI screens, the logical coordinates must be multiplied by the scaling factor to maintain physical consistency.

Consider a scenario where a rectangle is defined at coordinates (83, 104) with size (168, 211) on a standard display. On a 2x scaled display, these values must double to (166, 208) with size (336, 422) to occupy the same physical screen space.

void PieWidget::updateLayoutGeometry(const QSize &availableSize)
{
    // Apply scaling to base diameter constraints
    int scaledMinDiameter = applyDpiScaling(m_config.minDiameter);
    int finalDiameter;
    
    // Calculate available horizontal space, accounting for legend margins
    int availableWidth = availableSize.width();
    if (m_config.showLegend)
    {
        availableWidth -= applyDpiScaling(m_config.legendWidth * 2);
    }

    // Calculate available vertical space based on data series count
    int chartHeight;
    if (m_dataSeries.count() >= 1)
    {
        chartHeight = availableSize.height() 
                    - applyDpiScaling(m_config.barHeight) * m_dataSeries.count()
                    - applyDpiScaling(m_config.bottomMargin + m_config.spacing + m_config.barSpace * (m_dataSeries.count() - 1))
                    - applyDpiScaling(m_config.labelHeight * 2);
    }
    else
    {
        chartHeight = availableSize.height();
    }

    // Determine the bounding square for the pie
    if (availableWidth > chartHeight)
    {
        finalDiameter = chartHeight;
    }
    else
    {
        finalDiameter = availableWidth;
    }

    int startX, startY;
    int radius = finalDiameter - applyDpiScaling(m_config.minMargin * 2);
    int effectiveRadius = (radius > scaledMinDiameter) ? radius : scaledMinDiameter;

    if (m_config.showLegend)
    {
        m_layoutItems.resize(4);

        startX = width() / 2 - effectiveRadius / 2;
        startY = (chartHeight - effectiveRadius) / 2;

        // Position legends around the chart with scaled coordinates
        m_layoutItems[1].legendRect = QRect(applyDpiScaling(m_config.minMargin), applyDpiScaling(m_config.minMargin)
            , applyDpiScaling(m_config.legendWidth), applyDpiScaling(30));

        m_layoutItems[0].legendRect = QRect(size().width() - m_globalMargin - applyDpiScaling(m_config.legendWidth)
            , applyDpiScaling(m_config.minMargin)
            , applyDpiScaling(m_config.legendWidth), applyDpiScaling(30));

        m_layoutItems[3].legendRect = QRect(size().width() - m_globalMargin - applyDpiScaling(m_config.legendWidth)
            , chartHeight - applyDpiScaling(m_config.minMargin + 30)
            , applyDpiScaling(m_config.legendWidth), applyDpiScaling(30));

        m_layoutItems[2].legendRect = QRect(applyDpiScaling(m_config.minMargin)
            , chartHeight - applyDpiScaling(m_config.minMargin + 30)
            , applyDpiScaling(m_config.legendWidth), applyDpiScaling(30));

        m_layoutItems[0].isAligned = false;
        m_layoutItems[3].isAligned = false;
    }
    else
    {
        startX = applyDpiScaling(m_config.minMargin);
        startY = applyDpiScaling(m_config.minMargin);
    }

    // Set final scaled rectangles for rendering
    m_pieRect = QRect(startX, startY, effectiveRadius, effectiveRadius);
    m_barsRect = QRect(applyDpiScaling(20), 2 * startY + effectiveRadius + applyDpiScaling(m_config.spacing)
        , width() - applyDpiScaling(50)
        , size().height() - chartHeight);
}

The remaining drawing logic follows similar patterns, ensuring all geometric primitives used in the paint event are processed through the scaling function.