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:

1. Find in Widget Box: Look for "QCustomQRGenerator" in the custom widgets section
2. Drag to Designer: Drag the widget to your form
3. 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:

1. The data property contains valid text or URL
2. boxSize is at least 1 pixel
3. border is at least 0 modules
4. 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:

1. Ensure the image has transparent background for best results
2. Keep the logo size reasonable (recommended: 25% of QR code size)
3. 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.