QCustomQRGenerator

Overview

QCustomQRGenerator is a highly customizable QR code generation widget that provides extensive styling options, gradient effects, and advanced module patterns. It supports both basic and advanced QR code generation with real-time preview and multiple output formats.

Features

Advanced Styling: Multiple module shapes and gradient color masks
Real-time Generation: Instant QR code updates when properties change
Embedded Images: Support for center logos and icons
Transparency Support: Alpha channel support for backgrounds
Caching System: Performance optimization with smart caching
Multiple Output Formats: Save as PNG, JPEG, or copy to clipboard
Theme Integration: Automatic palette-based coloring
Qt Designer Ready: Full integration with Qt Designer

Installation

pip install QT-PyQt-PySide-Custom-Widgets

Basic Usage

Python Code

from Custom_Widgets.QCustomQRGenerator import QCustomQRGenerator
from qtpy.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QWidget, QPushButton

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        
        # Central widget
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # Create QR generator
        self.qr_generator = QCustomQRGenerator()
        
        # Configure basic properties
        self.qr_generator.data = "https://example.com"
        self.qr_generator.boxSize = 10
        self.qr_generator.border = 4
        self.qr_generator.fillColor = QColor(0, 0, 0)  # Black modules
        self.qr_generator.backgroundColor = QColor(255, 255, 255)  # White background
        
        layout.addWidget(self.qr_generator)
        
        # Add save button
        save_btn = QPushButton("Save QR Code")
        save_btn.clicked.connect(self.qr_generator.saveQRCode)
        layout.addWidget(save_btn)
        
app = QApplication([])
window = MainWindow()
window.show()
app.exec_()

Qt Designer Integration

The widget is available as a plugin in Qt Designer:

Find in Widget Box: Look for "QCustomQRGenerator" in the custom widgets section
Drag to Designer: Drag the widget to your form
Configure Properties: Use the property editor to customize QR code appearance

tip

Designer Tip: Use the property editor to quickly preview different QR code styles without writing code. Changes to properties instantly update the QR code display.

Property Reference

Basic QR Properties

Property	Type	Default	Description
`data`	str	"https://example.com"	Data to encode in QR code
`version`	int	None (auto)	QR code version (1-40), None for auto-detect
`errorCorrection`	str	"H"	Error correction level: "L", "M", "Q", "H"
`boxSize`	int	10	Size of each module in pixels
`border`	int	4	Border size in modules

Color Properties

Property	Type	Default	Description
`fillColor`	QColor	Text palette	Color of QR code modules
`backgroundColor`	QColor	Window palette	Background color
`gradientStartColor`	QColor	Highlight palette	Start color for gradient masks
`gradientEndColor`	QColor	Alternate base	End color for gradient masks

Advanced Styling

Property	Type	Default	Description
`moduleDrawer`	str	"square"	Module shape: "square", "gapped_square", "circle", "rounded", "vertical_bars", "horizontal_bars"
`colorMask`	str	"solid"	Color filling: "solid", "radial", "square", "horizontal", "vertical"
`sizeRatio`	float	1.0	Size ratio for gapped squares (0.1-1.0)
`embedImage`	bool	False	Enable embedded center image
`embeddedImageIcon`	QIcon	Empty	Icon to embed in center
`cacheEnabled`	bool	True	Enable caching for performance

Method Reference

Generation Methods

# Generate QR code with current settings
qr_generator.generateQRCode()

# Save QR code to file (opens dialog if no path provided)
qr_generator.saveQRCode("path/to/qrcode.png")

# Copy QR code to clipboard
qr_generator.copyToClipboard()

# Clear generation cache
qr_generator.clearCache()

Utility Methods

# Get current QR code as QPixmap
pixmap = qr_generator.getQRCodePixmap()

# Set embedded image from file dialog
success = qr_generator.setEmbeddedImageFromFileDialog()

# Resize QR display (automatically called on resize)
qr_generator.resizeQR()

Advanced Configuration

Complete Setup Example

from Custom_Widgets.QCustomQRGenerator import QCustomQRGenerator
from qtpy.QtGui import QColor, QIcon

# Create and configure QR generator
qr_generator = QCustomQRGenerator()

# Basic QR properties
qr_generator.data = "https://your-website.com"
qr_generator.version = 5  # Specific version
qr_generator.errorCorrection = "H"  # Highest error correction
qr_generator.boxSize = 12
qr_generator.border = 6

# Color configuration
qr_generator.fillColor = QColor(0, 100, 200)  # Blue modules
qr_generator.backgroundColor = QColor(240, 240, 240)  # Light gray background

# Advanced styling
qr_generator.moduleDrawer = "circle"  # Circular modules
qr_generator.colorMask = "radial"  # Radial gradient
qr_generator.gradientStartColor = QColor(0, 100, 200)  # Blue center
qr_generator.gradientEndColor = QColor(200, 100, 0)  # Orange edges

# Embedded image
qr_generator.embedImage = True
qr_generator.embeddedImageIcon = QIcon("path/to/logo.png")

# Generate the QR code
qr_generator.generateQRCode()

Module Drawer Examples

# Square modules (traditional)
qr_generator.moduleDrawer = "square"

# Gapped squares with adjustable spacing
qr_generator.moduleDrawer = "gapped_square"
qr_generator.sizeRatio = 0.7  # 70% size with gaps

# Circular modules
qr_generator.moduleDrawer = "circle"

# Rounded square modules  
qr_generator.moduleDrawer = "rounded"

# Vertical bar modules
qr_generator.moduleDrawer = "vertical_bars"

# Horizontal bar modules
qr_generator.moduleDrawer = "horizontal_bars"

Color Mask Examples

# Solid color (traditional)
qr_generator.colorMask = "solid"

# Radial gradient from center to edges
qr_generator.colorMask = "radial"

# Square gradient from center to corners  
qr_generator.colorMask = "square"

# Horizontal gradient left to right
qr_generator.colorMask = "horizontal"

# Vertical gradient top to bottom
qr_generator.colorMask = "vertical"

CSS Styling

Basic CSS Properties

QCustomQRGenerator {
    /* Main widget styling */
    background-color: palette(window);
    border: none;
    
    /* QR Code Color Properties */
    qproperty-fillColor: palette(text);
    qproperty-backgroundColor: palette(window);
    qproperty-gradientStartColor: palette(highlight);
    qproperty-gradientEndColor: palette(alternate-base);
}

QCustomQRGenerator QLabel {
    /* QR code display label */
    background-color: transparent;
    border: none;
    padding: 0px;
    margin: 0px;
}

Color Scheme Variants

/* Dark theme */
QCustomQRGenerator[colorScheme="dark"] {
    qproperty-fillColor: white;
    qproperty-backgroundColor: #2b2b2b;
    qproperty-gradientStartColor: #bb86fc;
    qproperty-gradientEndColor: #03dac6;
}

/* Light theme */
QCustomQRGenerator[colorScheme="light"] {
    qproperty-fillColor: black;
    qproperty-backgroundColor: white;
    qproperty-gradientStartColor: #6200ee;
    qproperty-gradientEndColor: #018786;
}

/* Blue theme */
QCustomQRGenerator[colorScheme="blue"] {
    qproperty-fillColor: #003366;
    qproperty-backgroundColor: #e6f2ff;
    qproperty-gradientStartColor: #0066cc;
    qproperty-gradientEndColor: #66b3ff;
}

Style Variants

/* Rounded modules */
QCustomQRGenerator[style="rounded"] {
    qproperty-moduleDrawer: "rounded";
}

/* Circular modules */
QCustomQRGenerator[style="circular"] {
    qproperty-moduleDrawer: "circle";
}

/* Gradient styling */
QCustomQRGenerator[style="gradient"] {
    qproperty-colorMask: "vertical";
    qproperty-moduleDrawer: "square";
}

JSON Styling Configuration

You can also configure the QR generator through JSON styling:

{
  "QCustomQRGenerator": [{
    "name": "mainQRCode",
    "data": "https://example.com",
    "boxSize": 10,
    "border": 4,
    "fillColor": "#000000",
    "backgroundColor": "#ffffff",
    "moduleDrawer": "square",
    "colorMask": "solid",
    "errorCorrection": "H",
    "cacheEnabled": true
  }]
}

Advanced JSON Configuration

{
  "QCustomQRGenerator": [{
    "name": "styledQR",
    "data": "https://your-app.com",
    "boxSize": 12,
    "border": 6,
    "fillColor": "#1a237e",
    "backgroundColor": "#f5f5f5",
    "moduleDrawer": "circle",
    "colorMask": "radial",
    "gradientStartColor": "#1a237e",
    "gradientEndColor": "#ffab00",
    "sizeRatio": 1.0,
    "embedImage": true,
    "errorCorrection": "Q"
  }]
}

Complete Examples

Basic QR Code Generator

from Custom_Widgets.QCustomQRGenerator import QCustomQRGenerator
from qtpy.QtWidgets import (QApplication, QMainWindow, QVBoxLayout, 
                           QWidget, QPushButton, QLineEdit, QColorDialog)
from qtpy.QtGui import QColor
from qtpy.QtCore import Qt

class QRGeneratorApp(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QR Code Generator")
        self.resize(400, 500)
        
        # Central widget
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # Data input
        self.data_input = QLineEdit()
        self.data_input.setPlaceholderText("Enter text or URL for QR code...")
        self.data_input.textChanged.connect(self.updateQRCode)
        layout.addWidget(self.data_input)
        
        # QR generator
        self.qr_generator = QCustomQRGenerator()
        self.qr_generator.data = "Enter text above"
        layout.addWidget(self.qr_generator)
        
        # Control buttons
        self.setupControlButtons(layout)
        
    def setupControlButtons(self, layout):
        # Color buttons
        fill_color_btn = QPushButton("Change Fill Color")
        fill_color_btn.clicked.connect(self.changeFillColor)
        layout.addWidget(fill_color_btn)
        
        bg_color_btn = QPushButton("Change Background Color")
        bg_color_btn.clicked.connect(self.changeBackgroundColor)
        layout.addWidget(bg_color_btn)
        
        # Style buttons
        circle_btn = QPushButton("Circle Modules")
        circle_btn.clicked.connect(lambda: self.setModuleStyle("circle"))
        layout.addWidget(circle_btn)
        
        square_btn = QPushButton("Square Modules")
        square_btn.clicked.connect(lambda: self.setModuleStyle("square"))
        layout.addWidget(square_btn)
        
        # Action buttons
        save_btn = QPushButton("Save QR Code")
        save_btn.clicked.connect(self.qr_generator.saveQRCode)
        layout.addWidget(save_btn)
        
        copy_btn = QPushButton("Copy to Clipboard")
        copy_btn.clicked.connect(self.qr_generator.copyToClipboard)
        layout.addWidget(copy_btn)
        
    def updateQRCode(self):
        self.qr_generator.data = self.data_input.text() or "Enter text above"
        
    def changeFillColor(self):
        color = QColorDialog.getColor(self.qr_generator.fillColor, self)
        if color.isValid():
            self.qr_generator.fillColor = color
            
    def changeBackgroundColor(self):
        color = QColorDialog.getColor(self.qr_generator.backgroundColor, self)
        if color.isValid():
            self.qr_generator.backgroundColor = color
            
    def setModuleStyle(self, style):
        self.qr_generator.moduleDrawer = style

app = QApplication([])
window = QRGeneratorApp()
window.show()
app.exec_()

Advanced Styled QR Code

from Custom_Widgets.QCustomQRGenerator import QCustomQRGenerator
from qtpy.QtWidgets import QApplication, QWidget, QVBoxLayout
from qtpy.QtGui import QColor, QIcon

class StyledQRExample(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout(self)
        
        # Create advanced QR code
        qr_generator = QCustomQRGenerator()
        
        # Professional styling
        qr_generator.data = "https://company.com/contact"
        qr_generator.boxSize = 15
        qr_generator.border = 8
        qr_generator.fillColor = QColor(30, 50, 100)  # Dark blue
        qr_generator.backgroundColor = QColor(245, 248, 250)  # Light blue-gray
        qr_generator.moduleDrawer = "rounded"
        qr_generator.colorMask = "vertical"
        qr_generator.gradientStartColor = QColor(30, 50, 100)  # Dark blue
        qr_generator.gradientEndColor = QColor(70, 130, 180)   # Steel blue
        
        # Add company logo
        qr_generator.embedImage = True
        qr_generator.embeddedImageIcon = QIcon("company_logo.png")
        
        layout.addWidget(qr_generator)

app = QApplication([])
window = StyledQRExample()
window.show()
app.exec_()

Troubleshooting

warning

Common Issue: If QR codes don't generate properly, ensure that:

The data property contains valid text or URL
boxSize is at least 1 pixel
border is at least 0 modules
Colors have sufficient contrast for scanning

tip

Performance Tip: For frequently updating QR codes, keep cacheEnabled set to True. For one-time generation with different data, set it to False to save memory.

warning

Embedded Image Warning: When using embedded images:

Ensure the image has transparent background for best results
Keep the logo size reasonable (recommended: 25% of QR code size)
Test scanability with different error correction levels

Debugging QR Generation

# Check if QR code generated successfully
pixmap = qr_generator.getQRCodePixmap()
if pixmap and not pixmap.isNull():
    print("QR code generated successfully")
else:
    print("QR code generation failed")
    
# Force regeneration (bypass cache)
qr_generator.clearCache()
qr_generator.generateQRCode()

Error Correction Guidelines

# Use lower error correction for simpler codes
qr_generator.errorCorrection = "L"  # 7% recovery
qr_generator.errorCorrection = "M"  # 15% recovery

# Use higher error correction for embedded images
qr_generator.errorCorrection = "Q"  # 25% recovery  
qr_generator.errorCorrection = "H"  # 30% recovery (recommended for logos)

Best Practices

Data Length and Version

# Short data - let version auto-detect
qr_generator.data = "https://short.url"
qr_generator.version = None  # Auto-detect

# Long data - specify version for consistency
qr_generator.data = "Very long text data that needs more space..."
qr_generator.version = 10  # Force specific version

Color Contrast

# Good contrast (recommended)
qr_generator.fillColor = QColor(0, 0, 0)      # Black
qr_generator.backgroundColor = QColor(255, 255, 255)  # White

# Poor contrast (avoid)
qr_generator.fillColor = QColor(100, 100, 100)      # Dark gray
qr_generator.backgroundColor = QColor(150, 150, 150)  # Light gray

Embedded Image Tips

# Best practices for embedded images
qr_generator.embedImage = True
qr_generator.errorCorrection = "H"  # Highest error correction
qr_generator.embeddedImageIcon = QIcon("logo.png")  # Square PNG with transparency

Additional Resources

QR Code Standards: ISO/IEC 18004:2015
Video Tutorials: SPINN TV YouTube Channel

The QCustomQRGenerator provides enterprise-grade QR code generation with extensive customization options, making it perfect for branding, marketing materials, and professional applications.

API reference

Generated from the widget's live metaobject — do not edit by hand.

Properties

Property	Type	Default
`data`	`string`	—
`version`	`int`	—
`errorCorrection`	`string`	—
`boxSize`	`int`	—
`border`	`int`	—
`fillColor`	`color`	—
`backgroundColor`	`color`	—
`cacheEnabled`	`bool`	—
`moduleDrawer`	`string`	—
`colorMask`	`string`	—
`gradientStartColor`	`color`	—
`gradientEndColor`	`color`	—
`sizeRatio`	`float`	—
`embedImage`	`bool`	—
`embeddedImageIcon`	`QIcon`	—

Methods

Method	Description
`backgroundColor(args, *kwargs)`	Background color.
`border(args, *kwargs)`	Border.
`boxSize(args, *kwargs)`	Box size.
`cacheEnabled(args, *kwargs)`	Cache enabled.
`clearCache()`	Clear the QR code cache.
`colorMask(args, *kwargs)`	Color mask.
`copyToClipboard()`	Copy the QR code to clipboard.
`data(args, *kwargs)`	Data.
`embedImage(args, *kwargs)`	Embed image.
`embeddedImageIcon(args, *kwargs)`	Embedded image icon.
`errorCorrection(args, *kwargs)`	Error correction.
`fillColor(args, *kwargs)`	Fill color.
`generateQRCode()`	Generate the QR code pixmap and set it to the QLabel.
`getQRCodePixmap()`	Get the current QR code as QPixmap.
`gradientEndColor(args, *kwargs)`	Gradient end color.
`gradientStartColor(args, *kwargs)`	Gradient start color.
`moduleDrawer(args, *kwargs)`	Module drawer.
`refreshQRCode()`	Refresh QR code when theme changes, only if colors are from palette.
`resizeQR()`	Scale pixmap to fit while maintaining aspect ratio
`saveQRCode(file_path=None)`	Save the generated QR code to file.
`setEmbeddedImageFromFileDialog()`	Open a file dialog to set the embedded image.
`sizeRatio(args, *kwargs)`	Size ratio.
`version(args, *kwargs)`	Version.

Overview​

Features​

Installation​

Basic Usage​

Python Code​

Qt Designer Integration​

Property Reference​

Basic QR Properties​

Color Properties​

Advanced Styling​

Method Reference​

Generation Methods​

Utility Methods​

Advanced Configuration​

Complete Setup Example​

Module Drawer Examples​

Color Mask Examples​

CSS Styling​

Basic CSS Properties​

Color Scheme Variants​

Style Variants​

JSON Styling Configuration​

Advanced JSON Configuration​

Complete Examples​

Basic QR Code Generator​

Advanced Styled QR Code​

Troubleshooting​

Debugging QR Generation​

Error Correction Guidelines​

Best Practices​

Data Length and Version​

Color Contrast​

Embedded Image Tips​

Additional Resources​

API reference​

Properties​

Methods​