Skip to main content

Qt Custom Widgets v2.0.3 Released - Enhanced Hamburger Menu & Performance Improvements

· 5 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

We're excited to announce the release of Qt Custom Widgets version 2.0.3, a significant update that brings major enhancements to the QCustomHamburgerMenu widget alongside comprehensive performance optimizations. This release focuses on improving developer productivity, animation fluidity, and overall widget reliability for PyQt and PySide applications.

V 2.0.2 Released

· 2 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

We're excited to announce the release of QT-PyQt-PySide-Custom-Widgets version 2.0.2! This update brings significant improvements to the project creation experience and introduces powerful automation features that will streamline your Qt development workflow.

What's New in v2.0.2​

Enhanced Project Creator​

The project creation wizard has been completely overhauled with:

  • Interactive Post-Creation Menu: Choose your next steps immediately after project setup
  • Automated File Monitoring: Real-time conversion of UI files as you design
  • One-Click Qt Designer Launch: Start designing with custom widgets instantly
  • Better User Guidance: Clear workflow instructions and command references

Automated File Monitoring​

Never manually convert UI files again! The new file monitoring feature:

  • Watches your ui/ folder for changes
  • Automatically converts .ui files to Python when you save
  • Supports all major Qt bindings (PySide6, PyQt5, PySide2, PyQt6)
  • Runs in the background while you work

Seamless Qt Designer Integration​

  • Launch Qt Designer directly with custom widgets pre-loaded
  • Access all custom widget categories:
    • MainWindow - Custom main windows
    • Sidebar - Navigation sidebars
    • Progressbars - Animated progress indicators
    • Component Container - Layout containers

Improved CLI Commands​

The command-line interface now includes:

# Start UI file monitoring
Custom_Widgets --monitor-ui ui --qt-library PySide6

# Launch Qt Designer with plugins
Custom_Widgets --start-designer --plugins

# Register custom widgets
Custom_Widgets --register-widgets

# Convert UI files manually
Custom_Widgets --convert-ui ui/main_window.ui
  1. Create Project: Custom_Widgets --create-project
  2. Design: Launch Qt Designer with custom widgets
  3. Monitor: Start file monitoring for automatic conversion
  4. Develop: See live updates as you design

Installation & Update​

New Installation:

pip install QT-PyQt-PySide-Custom-Widgets

Update Existing Installation:

pip install --upgrade QT-PyQt-PySide-Custom-Widgets

Bug Reports & Feedback​

Found an issue or have suggestions? Please report them on our GitHub Issues page: https://github.com/KhamisiKibet/Qt-PyQt-PySide-Custom-Widgets/issues

Special Thanks​

Thank you to all our contributors and the amazing community for your feedback and support! Your input helps make this library better with every release.

Happy coding!

Follow us for more updates:

#Python #Qt #PySide #PyQt #GUI #Development #OpenSource #CustomWidgets #Release

Custom Variables in JSon and QSS Style Sheets

· 6 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

In the Qt Custom Widgets framework, you can define custom variables in your JSON theme configuration and use them throughout your QSS stylesheets. This powerful feature allows you to create consistent, maintainable, and theme-aware styles for your applications.

warning

Important Note: Custom variables defined in "Other-variables" must be present in every CustomTheme object in your JSON file. If a theme is missing a variable that you use in your QSS, it will cause SCSS compilation errors when switching to that theme.

Defining Custom Variables in JSON​

You can add custom variables to any theme in your style.json file using the "Other-variables" section. Make sure to define the same variables in all themes:

{
  "Theme-name": "Qt-Dark-Theme",
  "Background-color": "#1e1e1e",
  "Text-color": "#e0e0e0",
  "Accent-color": "#41cd52",
  "Icons-color": "#41cd52",
  "Default-Theme": true,
  "Other-variables": {
    "CARD_RADIUS": "12px",
    "FOOTER_BG": "#111111",
    "NAV_BG": "#1e1e1e",
    "CARD_BG": "#2c2c2c",
    "BORDER_COLOR": "rgba(65, 205, 82, 0.3)",
    "HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.45)",
    "GRADIENT": "linear-gradient(135deg, #41cd52, #2fa440)",
    "SPACING_SM": "8px",
    "SPACING_MD": "16px",
    "SPACING_LG": "24px"
  }
},
{
  "Theme-name": "Qt-Light-Theme",
  "Background-color": "#ffffff",
  "Text-color": "#1e1e1e",
  "Accent-color": "#41cd52",
  "Icons-color": "#41cd52",
  "Default-Theme": false,
  "Other-variables": {
    "CARD_RADIUS": "12px",
    "FOOTER_BG": "#e5e5e5",
    "NAV_BG": "#f5f5f5",
    "CARD_BG": "#f8f8f8",
    "BORDER_COLOR": "rgba(65, 205, 82, 0.2)",
    "HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.25)",
    "GRADIENT": "linear-gradient(135deg, #41cd52, #2fa440)",
    "SPACING_SM": "8px",
    "SPACING_MD": "16px",
    "SPACING_LG": "24px"
  }
}
tip

Pro Tip: Create a template of your custom variables and copy it to every theme in your JSON file to ensure consistency and avoid missing variable errors.

Using Custom Variables in QSS​

Once defined, these variables become available in your QSS/SCSS files and can be used just like the auto-generated theme variables:

Basic Usage Examples​

// Card components using custom variables
QFrame#card {
    background-color: $CARD_BG;
    border-radius: $CARD_RADIUS;
    border: 1px solid $BORDER_COLOR;
    margin: $SPACING_MD;
    
    &:hover {
        box-shadow: $HOVER_GLOW;
    }
}

// Navigation using custom background
QWidget#navigation {
    background-color: $NAV_BG;
    border-right: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
}

// Footer styling
QWidget#footer {
    background-color: $FOOTER_BG;
    border-top: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
}

Advanced Usage with Gradients​

// Using custom gradient variables
QMainWindow#gradientBackground {
    background: $GRADIENT;
}

// Creating derived gradients
QFrame#header {
    background: qlineargradient(
        x1:0, y1:0, x2:1, y2:0,
        stop:0 $CARD_BG,
        stop:1 $NAV_BG
    );
    border-radius: $CARD_RADIUS;
}

Consistent Spacing System​

// Using spacing variables for consistency
QWidget#container {
    padding: $SPACING_LG;
}

QPushButton {
    padding: $SPACING_SM $SPACING_MD;
    margin: $SPACING_SM;
}

QLabel {
    margin: $SPACING_SM;
}

QVBoxLayout, QHBoxLayout {
    spacing: $SPACING_MD;
    margin: $SPACING_SM;
}

Complete Theme-Aware QSS Example​

Here's a complete QSS stylesheet that leverages both auto-generated and custom variables:

// ===================================================
// APPLICATION LAYOUT STYLES
// ===================================================

QMainWindow, #centralwidget {
    background-color: $COLOR_BACKGROUND_1;
    padding: $SPACING_MD;
}

// ===================================================
// CARD SYSTEM
// ===================================================

QFrame#card {
    background-color: $CARD_BG;
    border-radius: $CARD_RADIUS;
    border: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
    
    &:hover {
        box-shadow: $HOVER_GLOW;
    }
}

QFrame#card QLabel#title {
    color: $COLOR_TEXT_1;
    font-size: 16px;
    font-weight: bold;
    margin-bottom: $SPACING_SM;
}

QFrame#card QLabel#content {
    color: $COLOR_TEXT_2;
    font-size: 14px;
    margin-bottom: $SPACING_SM;
}

// ===================================================
// NAVIGATION SYSTEM
// ===================================================

QWidget#navigation {
    background-color: $NAV_BG;
    border-right: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
}

QPushButton#navButton {
    background-color: transparent;
    color: $COLOR_TEXT_2;
    text-align: left;
    padding: $SPACING_MD;
    border-radius: calc($CARD_RADIUS / 2);
    margin: 2px $SPACING_SM;
    
    &:hover {
        background-color: $COLOR_BACKGROUND_2;
        color: $COLOR_TEXT_1;
    }
    
    &:checked {
        background-color: $COLOR_ACCENT_1;
        color: $COLOR_BACKGROUND_1;
    }
}

// ===================================================
// FORM SYSTEM
// ===================================================

QLineEdit, QComboBox, QTextEdit {
    background-color: $COLOR_BACKGROUND_2;
    color: $COLOR_TEXT_1;
    border: 1px solid $BORDER_COLOR;
    border-radius: calc($CARD_RADIUS / 3);
    padding: $SPACING_SM $SPACING_MD;
    font-size: 14px;
    margin-bottom: $SPACING_SM;
    
    &:focus {
        border-color: $COLOR_ACCENT_1;
        background-color: $COLOR_BACKGROUND_3;
    }
}

// ===================================================
// BUTTON VARIANTS
// ===================================================

QPushButton {
    background-color: $COLOR_BACKGROUND_2;
    color: $COLOR_TEXT_1;
    border: 1px solid $BORDER_COLOR;
    border-radius: calc($CARD_RADIUS / 2);
    padding: $SPACING_SM $SPACING_MD;
    font-weight: 500;
    margin: $SPACING_SM;
    
    &:hover {
        background-color: $COLOR_ACCENT_1;
        color: $COLOR_BACKGROUND_1;
    }
}

QPushButton#primaryButton {
    background-color: $COLOR_ACCENT_1;
    color: $COLOR_BACKGROUND_1;
    font-weight: bold;
}

QPushButton#secondaryButton {
    background-color: $CARD_BG;
    color: $COLOR_TEXT_1;
}

// ===================================================
// LAYOUT COMPONENTS
// ===================================================

QWidget#header {
    background-color: $NAV_BG;
    border-bottom: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
}

QWidget#footer {
    background-color: $FOOTER_BG;
    border-top: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
}

QWidget#sidebar {
    background-color: $CARD_BG;
    border-right: 1px solid $BORDER_COLOR;
    padding: $SPACING_MD;
}

// ===================================================
// UTILITY STYLES USING OBJECT NAMES
// ===================================================

// Text utilities
QLabel#textTitle {
    color: $COLOR_TEXT_1;
    font-size: 18px;
    font-weight: bold;
    margin-bottom: $SPACING_MD;
}

QLabel#textSubtitle {
    color: $COLOR_TEXT_2;
    font-size: 14px;
    margin-bottom: $SPACING_SM;
}

QLabel#textMuted {
    color: $COLOR_TEXT_3;
    font-size: 12px;
}

// Background utilities
QWidget#bgCard {
    background-color: $CARD_BG;
    border-radius: $CARD_RADIUS;
    padding: $SPACING_MD;
}

QWidget#bgNav {
    background-color: $NAV_BG;
}

QWidget#bgFooter {
    background-color: $FOOTER_BG;
}

// Border utilities
QWidget#borderAll {
    border: 1px solid $BORDER_COLOR;
    border-radius: $CARD_RADIUS;
}

QWidget#borderBottom {
    border-bottom: 1px solid $BORDER_COLOR;
}

QWidget#borderTop {
    border-top: 1px solid $BORDER_COLOR;
}
warning

Troubleshooting Tip: If you encounter SCSS compilation errors when switching themes, check that all custom variables used in your QSS are defined in the currently active theme's "Other-variables" section.

Best Practices for Custom Variables​

1. Semantic Variable Names​

Use names that describe the purpose, not the value:

"Other-variables": {
    "CARD_RADIUS": "12px",           // Good
    "HEADER_HEIGHT": "60px",         // Good
    "PRIMARY_SPACING": "16px",       // Good
    "blue_color": "#41cd52"          // Avoid - too specific
}

2. Create a Design System​

Define a consistent set of variables and ensure they exist in all themes:

"Other-variables": {
    // Spacing scale
    "SPACING_XS": "4px",
    "SPACING_SM": "8px", 
    "SPACING_MD": "16px",
    "SPACING_LG": "24px",
    "SPACING_XL": "32px",
    
    // Border radius scale
    "RADIUS_SM": "4px",
    "RADIUS_MD": "8px",
    "RADIUS_LG": "12px",
    "RADIUS_XL": "16px",
    
    // Component-specific
    "CARD_BG": "#2c2c2c",
    "NAV_BG": "#1e1e1e",
    "HEADER_HEIGHT": "60px"
}
tip

Consistency Tip: Create a master list of your custom variables and use it as a checklist when adding new themes to ensure you don't miss any variables.

3. Theme-Specific Adjustments​

You can override variables for specific themes while keeping the same variable names:

{
  "Theme-name": "Qt-Light-Theme",
  "Background-color": "#ffffff",
  "Text-color": "#1e1e1e",
  "Other-variables": {
    "CARD_BG": "#f8f8f8",
    "NAV_BG": "#f5f5f5",
    "FOOTER_BG": "#e5e5e5",
    "BORDER_COLOR": "rgba(65, 205, 82, 0.2)",
    "HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.25)",
    // Keep all other variables the same as other themes
    "SPACING_SM": "8px",
    "SPACING_MD": "16px",
    "CARD_RADIUS": "12px"
  }
}

4. Using Variables in Python Code​

You can also access these variables in your Python code:

from Custom_Widgets.QAppSettings import QAppSettings

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # Access theme variables
        card_radius = self.theme.CARD_RADIUS
        spacing_md = self.theme.SPACING_MD
        
        # Use in dynamic styling
        self.ui.some_widget.setStyleSheet(f"""
            border-radius: {card_radius};
            padding: {spacing_md};
        """)
warning

Development Note: When adding new custom variables to your QSS, remember to update all themes in your JSON file with the new variables to prevent theme switching errors.

Benefits of Using Custom Variables​

  1. Consistency: Ensure visual consistency across your application
  2. Maintainability: Change values in one place to update everywhere
  3. Theme Cohesion: Custom variables work seamlessly with theme switching
  4. Developer Experience: Clear, semantic variable names improve code readability
  5. Scalability: Easy to add new components that follow the same design system

By leveraging custom variables in your JSON themes, you create a robust, maintainable styling system that scales with your application and provides a consistent user experience across different themes.

Getting Started With Qt Custom Widgets

· 8 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

Step 1: Install Python and Create Virtual Environment​

Install Python​

First, ensure you have Python 3.7 or higher installed:

Windows:

# Download from python.org or use winget
winget install Python.Python.3.11

macOS:

# Using Homebrew
brew install python

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3 python3-pip python3-venv

Create Virtual Environment​

Always use a virtual environment to manage dependencies:

# Create project directory
mkdir my_qt_project
cd my_qt_project

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

Your terminal should now show (venv) indicating the virtual environment is active.

Step 2: Install Qt Binding​

Important: Make sure your virtual environment is activated (you see (venv) in your terminal).

Choose and install one of these Qt bindings:

pip install PySide6

Option 2: PyQt6​

pip install PyQt6

Option 3: PySide2​

pip install PySide2

Option 4: PyQt5​

pip install PyQt5

Note: For this tutorial, we'll use PySide6 as it's the most modern and freely available.

Step 3: Install Custom Widgets​

Install the custom widgets package (make sure venv is active):

pip install QT-PyQt-PySide-Custom-Widgets

Verify installation:

python -c "import Custom_Widgets; print('Custom Widgets installed successfully!')"

Step 4: Create Your First Project​

Important: Run this command from INSIDE your activated virtual environment folder:

# You should be in your project directory with venv activated
# Your terminal should show: (venv) path/to/your/project$

# Run project creator FROM INSIDE THE VENV FOLDER
Custom_Widgets --create-project

What happens when you run the project creator:

  1. It detects your current directory as the project location
  2. It checks if the folder is empty (or only contains logs)
  3. It guides you through the setup process interactively

The project creator will guide you through:

  1. Qt Binding Selection: Choose your Qt library
  2. Color Scheme: Select icons and theme colors
  3. App Information: Enter app name and organization details
  4. Automatic Setup: Creates all necessary files and folders

Correct Folder Structure Example:​

my_qt_project/          # Your project folder
├── venv/               # Virtual environment (already created)
│   ├── bin/            # or Scripts/ on Windows
│   ├── lib/
│   └── pyvenv.cfg
└── (project files will be created here by the creator)

Common Mistake to Avoid:

  • Don't run the command from inside the venv folder
  • Run it from your project root folder where venv is located

Method B: Manual Setup (For Advanced Users)​

If you prefer manual setup, create this structure in your project root:

my_qt_project/
├── venv/               # Virtual environment
├── main.py             # Main application file
├── ui/                 # UI files directory
│   └── main_window.ui
├── json-styles/        # Theme configuration
│   └── style.json
├── requirements.txt    # Dependencies
└── README.md          # Documentation

Step 5: Understanding the Project Structure​

After running the project creator from inside your venv folder, you'll have:

my_qt_project/
├── venv/               # Virtual environment
├── main.py              # Main application file
├── ui/                  # UI files directory
│   └── QCustomQMainWindow.ui
├── json-styles/         # Theme configuration
│   └── style.json
├── requirements.txt     # Dependencies
└── README.md           # Documentation

Step 6: Register Custom Widgets with Qt Designer​

Before designing your interface, register the custom widgets (from your activated venv):

# Register widgets with Qt Designer
Custom_Widgets --register-widgets

Expected Output:

Registering QCustomQMainWindow...
Registering QCustomSidebar...
Registering QCustomProgressBar...
... (all widgets registered successfully)

Step 7: Launch Qt Designer with Custom Widgets​

Start Qt Designer with the custom widgets loaded (from activated venv):

# Launch Qt Designer with custom widgets
Custom_Widgets --start-designer --plugins

Alternative methods:

# If the above doesn't work, try:
designer
# or
pyside6-designer
# or
qt5-designer

Step 8: Designing Your Interface in Qt Designer​

Finding Custom Widgets​

When Qt Designer opens, look for these widget groups in the widget box:

  1. MainWindow Section:

    • QCustomQMainWindow - Enhanced main window with theme support

  2. Sidebar Section:

    • QCustomSidebar - Customizable sidebar navigation
    • QCustomSidebarButton - Buttons for sidebar
    • QCustomSidebarLabel - Labels for sidebar

  3. Progressbars Section:

    • QCustomRoundProgressBar - Circular progress indicator
    • AnalogGaugeWidget - Analog gauge display

  4. Component Container Section:

    • QCustomComponent - Container for organizing widgets
    • QCustomComponentContainer - Main container component

Step-by-Step Design Process​

  1. Start with QCustomQMainWindow:

    • Drag QCustomQMainWindow from the widget box to the form
    • This becomes your main application window

  2. Add a Sidebar:

    • Drag QCustomSidebar to the left side of your main window
    • Add QCustomSidebarButton widgets inside the sidebar
    • Set button text and icons in the property editor

  3. Add Content Area:

    • Use QCustomComponent as content containers
    • Add standard Qt widgets (buttons, labels, etc.) inside components
    • Use QCustomQStackedWidget to manage multiple pages

  4. Style Your Interface:

    • Use the property editor to set object names
    • Apply custom styles through the JSON configuration later

  5. Save Your Design:

    • Save the file as main_window.ui in the ui/ folder
    • Qt Designer files use .ui extension

Step 9: Automatic UI File Conversion​

Keep this running while you design (from activated venv):

# Monitor UI folder for changes
Custom_Widgets --monitor-ui ui --qt-library PySide6

What this does:

  • Watches the ui/ folder for any changes
  • Automatically converts .ui files to Python when you save
  • Updates your application in real-time

Manual Conversion​

If you prefer manual conversion:

# Convert specific file
Custom_Widgets --convert-ui ui/main_window.ui --qt-library PySide6

# Convert all files in folder
Custom_Widgets --convert-ui ui --qt-library PySide6

Step 10: Customize Your App Theme​

Edit the json-styles/style.json file to customize your app's appearance:

{
    "QtBinding": "PySide6",
    "QMainWindow": {
        "title": "My Awesome App"
    },
    "QSettings": {
        "AppSettings": {
            "OrginizationName": "My Company",
            "ApplicationName": "My App",
            "OrginizationDormain": "myapp.org"
        },
        "ThemeSettings": {
            "QtDesignerIconsColor": "#ffffff",
            "CustomThemes": [
                {
                    "Background-color": "#2b2b2b",
                    "Text-color": "#ffffff",
                    "Accent-color": "#0078d4",
                    "Icons-color": "#ffffff",
                    "Theme-name": "Default Dark",
                    "Default-Theme": true
                }
            ]
        }
    }
}

Key Configuration Options:

  • Background-color: Main app background
  • Text-color: Default text color
  • Accent-color: Primary accent color for buttons, highlights
  • Icons-color: Color of all icons in the app

Step 11: Run Your Application​

Execute your application (from activated venv):

python main.py

Your custom-styled application should launch with:

  • The theme colors you configured
  • All custom widgets functioning
  • Your designed interface layout

Step 12: Development Workflow Tips​

Efficient Development Cycle​

  1. Activate Venv: Always start with source venv/bin/activate (or venv\Scripts\activate on Windows)
  2. Design: Work in Qt Designer with custom widgets
  3. Save: Save your .ui file (auto-conversion happens if monitoring)
  4. Test: Run your app to see changes
  5. Repeat: Go back to design and continue iterating

Useful Commands for Daily Use (Run from activated venv)​

# Start monitoring when beginning work
Custom_Widgets --monitor-ui ui --qt-library PySide6

# Launch designer when needed
Custom_Widgets --start-designer --plugins

# Run your app
python main.py

Complete Workflow Example​

# 1. Start fresh each day
cd my_qt_project
source venv/bin/activate  # or venv\Scripts\activate on Windows

# 2. Start file monitoring (keep this terminal open)
Custom_Widgets --monitor-ui ui --qt-library PySide6

# 3. In another terminal, launch designer
cd my_qt_project
source venv/bin/activate
Custom_Widgets --start-designer --plugins

# 4. When ready to test
python main.py

Step 13: Advanced Customization​

Creating Multiple Themes​

Add additional themes to your style.json:

"CustomThemes": [
    {
        "Background-color": "#2b2b2b",
        "Text-color": "#ffffff",
        "Accent-color": "#0078d4",
        "Icons-color": "#ffffff",
        "Theme-name": "Dark Blue",
        "Default-Theme": true
    },
    {
        "Background-color": "#f0f0f0",
        "Text-color": "#000000",
        "Accent-color": "#e74c3c",
        "Icons-color": "#000000",
        "Theme-name": "Light Red",
        "Default-Theme": false
    }
]

Custom Widget Properties​

Each custom widget has specific properties you can set in Qt Designer:

  • QCustomSidebar: backgroundColor, activeColor, iconSize
  • QCustomProgressBar: progressColor, background_color, text_color
  • QCustomQMainWindow: enableCustomTitleBar, enableGradient

Troubleshooting Common Issues​

Virtual Environment Issues​

# Check if venv is activated
which python  # Should point to venv directory

# If not activated:
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

Widgets Not Showing in Qt Designer​

# Re-register widgets (from activated venv)
Custom_Widgets --register-widgets

# Restart Qt Designer
Custom_Widgets --start-designer --plugins

UI Files Not Converting​

# Check if monitoring is running (from activated venv)
Custom_Widgets --monitor-ui ui --qt-library PySide6

# Manual conversion (from activated venv)
Custom_Widgets --convert-ui ui/main_window.ui --qt-library PySide6

Import Errors​

# Ensure package is installed in venv
pip install QT-PyQt-PySide-Custom-Widgets

# Check virtual environment is activated
which python  # Should point to venv directory

Project Creator Not Working​

# Make sure you're in the correct directory
pwd  # Should show your project folder, not inside venv

# Check folder contents
ls -la  # Should show venv folder and your project files

# If you accidentally ran creator in wrong location:
# Delete the generated files and run again from correct location

Next Steps​

Now that you have a basic application running:

  1. Explore More Widgets: Try different custom widgets in your designs
  2. Custom Styles: Experiment with different color schemes in the JSON file
  3. Advanced Layouts: Combine custom widgets with standard Qt widgets
  4. Animation: Add transitions and animations to your interface
  5. Database Integration: Connect your GUI to databases or APIs

Resources​

Congratulations! You've successfully set up a Qt application with custom widgets using proper virtual environment practices. The automated workflow will make your development process much smoother as you continue building your application.

Key Takeaway: Always remember to activate your virtual environment before running any Custom_Widgets commands or your Python application!

Qt Theme Styling Guide: Json Stylesheet

· 4 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

In this guide, we'll walk through creating professional Qt Dark and Light themes for your custom widgets applications. These themes follow Qt's design language while providing modern, visually appealing interfaces.

Theme Color Palettes​

Qt Dark Theme Colors​

  • Background: #1e1e1e (Dark gray)
  • Text: #e0e0e0 (Light gray)
  • Accent: #41cd52 (Qt green)
  • Icons: #41cd52 (Qt green)
  • Cards: #2c2c2c (Slightly lighter dark gray)
  • Footer: #111111 (Near black)

Qt Light Theme Colors​

  • Background: #ffffff (Pure white)
  • Text: #1e1e1e (Dark gray)
  • Accent: #41cd52 (Qt green)
  • Icons: #41cd52 (Qt green)
  • Cards: #f8f8f8 (Off-white)
  • Footer: #e5e5e5 (Light gray)

Complete Theme Configuration​

Here's how to implement both themes in your style.json:

{
  "QSettings": [
    {
      "ThemeSettings": {
        "QtDesignerIconsColor": "#41CD52",
        "CustomThemes": [
          {
            "Theme-name": "Qt-Dark-Theme",
            "Background-color": "#1e1e1e",
            "Text-color": "#e0e0e0",
            "Accent-color": "#41cd52",
            "Icons-color": "#41cd52",
            "Default-Theme": true,
            "Create-icons": true,
            "Other-variables": {
              "CARD_RADIUS": "12px",
              "FOOTER_BG": "#111111",
              "NAV_BG": "#1e1e1e",
              "CARD_BG": "#2c2c2c",
              "BORDER_COLOR": "rgba(65, 205, 82, 0.3)",
              "HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.45)",
              "GRADIENT": "linear-gradient(135deg, #41cd52, #2fa440)"
            }
          },
          {
            "Theme-name": "Qt-Light-Theme",
            "Background-color": "#ffffff",
            "Text-color": "#1e1e1e",
            "Accent-color": "#41cd52",
            "Icons-color": "#41cd52",
            "Default-Theme": false,
            "Create-icons": true,
            "Other-variables": {
              "CARD_RADIUS": "12px",
              "FOOTER_BG": "#e5e5e5",
              "NAV_BG": "#f5f5f5",
              "CARD_BG": "#f8f8f8",
              "BORDER_COLOR": "rgba(65, 205, 82, 0.2)",
              "HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.25)",
              "GRADIENT": "linear-gradient(135deg, #41cd52, #2fa440)"
            }
          }
        ]
      }
    }
  ]
}

Key Design Principles​

1. Color Contrast​

  • Dark Theme: High contrast between background (#1e1e1e) and text (#e0e0e0)
  • Light Theme: Strong contrast between background (#ffffff) and text (#1e1e1e)
  • Accessibility: Both themes maintain WCAG AA compliance for text readability

2. Consistent Accent Color​

  • Uses Qt's signature green (#41cd52) across both themes
  • Provides visual consistency when switching between themes
  • Green color represents Qt's brand identity

3. Layered Backgrounds​

  • Dark Theme: Three levels of darkness for depth
  • Light Theme: Three levels of lightness for hierarchy
  • Each layer serves a specific purpose in the UI

4. Modern Effects​

  • Border Radius: Consistent 12px rounded corners
  • Shadows: Theme-appropriate glow effects
  • Gradients: Subtle green gradients for visual interest

Theme Variables Explained​

Core Colors​

  • Background-color: Main application background
  • Text-color: Primary text color for readability
  • Accent-color: Primary brand color for interactive elements
  • Icons-color: Color for all icon assets

Additional Variables​

  • CARD_RADIUS: Border radius for cards and containers
  • FOOTER_BG: Background color for footer areas
  • NAV_BG: Background for navigation elements
  • CARD_BG: Background for card components
  • BORDER_COLOR: Border colors with theme-appropriate opacity
  • HOVER_GLOW: Shadow effects for interactive states
  • GRADIENT: CSS gradients for visual enhancements

Implementation Tips​

1. Setting Default Theme​

"Default-Theme": true

Set this to true for your preferred default theme. The other theme should have false.

2. Icon Generation​

"Create-icons": true

This ensures icons are automatically generated in your theme colors.

3. Opacity Adjustments​

Notice how border colors use rgba with different opacity:

  • Dark theme: rgba(65, 205, 82, 0.3) (more visible)
  • Light theme: rgba(65, 205, 82, 0.2) (more subtle)

4. Shadow Intensity​

  • Dark theme shadows are more pronounced (0.45 opacity)
  • Light theme shadows are more subtle (0.25 opacity)

Theme Switching​

To implement theme switching in your application:

  1. Set one theme as default with "Default-Theme": true
  2. Use the other theme for the alternative mode
  3. Implement a toggle mechanism in your UI
  4. Reload the theme configuration when switching

Benefits of This Approach​

1. Brand Consistency​

  • Maintains Qt's visual identity with the green accent color
  • Professional appearance suitable for commercial applications

2. User Experience​

  • Dark theme reduces eye strain in low-light environments
  • Light theme provides familiarity for traditional desktop apps
  • Smooth transitions between themes

3. Developer Experience​

  • Clear variable naming makes customization easy
  • Consistent design tokens across all components
  • Easy to extend with additional color variations

4. Performance​

  • Efficient color scheme with minimal variables
  • Optimized for both dark and light mode rendering

Customization Examples​

Changing Accent Color​

To use a different accent color, simply replace all instances of #41cd52 with your preferred color:

"Accent-color": "#0078d4",
"Icons-color": "#0078d4",
"QtDesignerIconsColor": "#0078d4"

Adjusting Contrast​

For higher contrast in the dark theme:

"Background-color": "#121212",
"Text-color": "#ffffff"

Modifying Border Radius​

For softer or sharper corners:

"CARD_RADIUS": "8px"  // Softer
"CARD_RADIUS": "16px" // Rounder

Conclusion​

These Qt Dark and Light themes provide a solid foundation for creating professional applications with custom widgets. The color schemes are carefully chosen to be both aesthetically pleasing and functionally effective, following modern design principles while staying true to Qt's visual identity.

Remember to test your themes in different lighting conditions and consider user preferences when deciding which theme to set as default. The flexibility of this system allows you to easily create additional theme variations or customize the existing ones to match your specific application needs.

For more advanced theming options, refer to the Custom Widgets documentation on GitHub and explore additional styling variables available for specific widget types.

Qt Theme Styling Guide: Qss/Css Stylesheet

· 4 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

This guide explains how to use the auto-generated theme variables in your QSS/SCSS files to create dynamic, theme-aware styles for your Qt applications.

Understanding Auto-Generated Theme Variables​

When you define themes in your style.json file, the Custom Widgets system automatically generates SCSS variables that you can use throughout your stylesheets. These variables are created based on your theme colors and custom variables.

Core Color Variables​

The system generates a comprehensive color palette from your base theme colors:

  • Background colors: $COLOR_BACKGROUND_1 through $COLOR_BACKGROUND_6 (6 shades from light to dark)
  • Text colors: $COLOR_TEXT_1 through $COLOR_TEXT_4 (4 shades from light to dark)
  • Accent colors: $COLOR_ACCENT_1 through $COLOR_ACCENT_4 (4 shades from light to dark)
  • RGB components: Individual RGB values for each color (e.g., $CB1_R, $CB1_G, $CB1_B for background colors)

Additional Generated Variables​

  • Borders: Pre-defined border styles ($BORDER_1, $BORDER_2, $BORDER_3)
  • Selection borders: Accent-colored borders ($BORDER_SELECTION_1, etc.)
  • Border radius: $SIZE_BORDER_RADIUS
  • Tooltip opacity: $OPACITY_TOOLTIP
  • Resource paths: $PATH_RESOURCES, $RELATIVE_FOLDER

Custom Theme Variables​

Variables defined in your JSON theme under "Other-variables" are also available:

"Other-variables": {
  "CARD_RADIUS": "12px",
  "FOOTER_BG": "#0f0f0f",
  "NAV_BG": "#1e1e1e"
}

Using Theme Variables in QSS/SCSS​

Basic Widget Styling​

QWidget {
    background-color: $COLOR_BACKGROUND_1;
    color: $COLOR_TEXT_1;
}

QPushButton {
    background-color: $COLOR_ACCENT_1;
    color: $COLOR_TEXT_1;
    border-radius: $SIZE_BORDER_RADIUS;
    border: $BORDER_1;
}

Creating Gradients with RGB Components​

Use the RGB variables to create dynamic gradients:

QFrame#gradientFrame {
    background: qlineargradient(
        x1:0, y1:0, x2:1, y2:1,
        stop:0 rgba($CB1_R, $CB1_G, $CB1_B, 255),
        stop:1 rgba($CB3_R, $CB3_G, $CB3_B, 255)
    );
}

Component-Specific Styling​

// Cards with custom radius
QFrame#card {
    background-color: $COLOR_BACKGROUND_2;
    border-radius: $CARD_RADIUS;
    border: $BORDER_2;
}

// Navigation elements
QWidget#navigation {
    background-color: $NAV_BG;
}

// Footer styling
QWidget#footer {
    background-color: $FOOTER_BG;
}

Complex Component Styling​

For more complex components, you can create custom variables:

// Define custom gradients using theme variables
$MY_GRADIENT: qlineargradient(
    x1:0, y1:0, x2:1, y2:0.869,
    stop:0 $COLOR_BACKGROUND_1,
    stop:1 $COLOR_BACKGROUND_3
);

QMainWindow#customWindow {
    background: $MY_GRADIENT;
    
    QPushButton {
        background-color: $COLOR_ACCENT_2;
        &:hover {
            background-color: $COLOR_ACCENT_1;
        }
    }
}

Form Elements with Dynamic Borders​

QLineEdit, QComboBox {
    background-color: $COLOR_BACKGROUND_2;
    border: 2px solid $COLOR_BACKGROUND_4;
    border-radius: 8px;
    padding: 8px;
    
    &:focus {
        border-color: $COLOR_ACCENT_1;
    }
}

Status Indicators​

// Use accent colors for status indicators
.status-success {
    color: $COLOR_ACCENT_1;
    border: 1px solid $COLOR_ACCENT_1;
}

.status-warning {
    color: $COLOR_ACCENT_2;
    border: 1px solid $COLOR_ACCENT_2;
}

.status-error {
    color: $COLOR_ACCENT_3;
    border: 1px solid $COLOR_ACCENT_3;
}

Best Practices​

1. Use Semantic Variable Names​

Create meaningful variable names for your custom styles:

$CARD_BACKGROUND: $COLOR_BACKGROUND_2;
$HEADER_TEXT: $COLOR_TEXT_1;
$BUTTON_PRIMARY: $COLOR_ACCENT_1;

2. Leverage the Color Hierarchy​

  • Use $COLOR_BACKGROUND_1 for main backgrounds
  • Use $COLOR_BACKGROUND_2 for cards and panels
  • Use $COLOR_BACKGROUND_3 for nested elements
  • Use accent colors for interactive elements

3. Create Reusable Mixins​

For complex styles, create SCSS mixins:

@mixin card-style {
    background-color: $COLOR_BACKGROUND_2;
    border-radius: $CARD_RADIUS;
    border: $BORDER_2;
    padding: 16px;
}

.my-card {
    @include card-style;
}

4. Use RGB Components for Transparency​

Create semi-transparent overlays using RGB variables:

.overlay {
    background-color: rgba($CB1_R, $CB1_G, $CB1_B, 0.8);
}

5. Theme-Aware Animations​

Create animations that work with any theme:

QPushButton {
    background-color: $COLOR_ACCENT_2;
    transition: background-color 0.3s ease;
    
    &:hover {
        background-color: $COLOR_ACCENT_1;
    }
}

Dynamic Theme Switching​

When users switch themes, all variables are automatically updated, and your styles will reflect the new color scheme without any code changes.

Example: Complete Component​

// Dashboard card component
#DashboardCard {
    background: qlineargradient(
        x1:0, y1:0, x2:1, y2:1,
        stop:0 $COLOR_BACKGROUND_2,
        stop:1 $COLOR_BACKGROUND_3
    );
    border-radius: $CARD_RADIUS;
    border: $BORDER_2;
    
    QLabel#title {
        color: $COLOR_TEXT_1;
        font-size: 16px;
        font-weight: bold;
    }
    
    QLabel#value {
        color: $COLOR_ACCENT_1;
        font-size: 24px;
        font-weight: bold;
    }
    
    QPushButton#action {
        background-color: $COLOR_ACCENT_2;
        color: $COLOR_TEXT_1;
        border-radius: 6px;
        padding: 8px 16px;
        
        &:hover {
            background-color: $COLOR_ACCENT_1;
        }
    }
}

By using these auto-generated theme variables, you create styles that automatically adapt to any theme defined in your JSON configuration, ensuring consistency and making theme switching seamless for your users.

V 2.0.1 Released

· 3 min read
Khamisi Kibet
Khamisi Kibet
Creator of Qt Custom Widgets

Qt Custom Widgets v2.0.1 Released​

We’re excited to announce the release of Qt Custom Widgets 2.0.1 — a refined update that brings even more power and flexibility to your PyQt and PySide GUI development.

This release focuses on performance improvements, new custom widgets, and a streamlined command-line interface (CLI) that now lets you launch Qt Designer with all custom widgets preloaded.

What’s New in 2.0.1​

More Custom Widgets​

This version introduces several new widgets designed to enhance both functionality and design flexibility. Each widget can be used directly in Qt Designer or instantiated in Python code, fully integrated with your preferred Qt library (PySide6, PySide2, PyQt6, or PyQt5).

Launch Qt Designer with Plugins​

The new CLI now supports launching Qt Designer directly from your environment, with optional loading of all Custom Widgets plugins.

To open Designer with your custom widgets automatically loaded, simply run:

Custom_Widgets --start-designer --plugins

If you prefer to launch Designer without plugins, just run:

Custom_Widgets --start-designer

This feature ensures a seamless integration between your environment and Designer, making your workflow faster and more reliable.

Improved JSON Stylesheet​

The JSON-based stylesheet system has been updated for better theme management. You can now apply light, dark, or custom themes more efficiently with improved property mapping and rendering accuracy.

Minor Fixes and Performance Improvements​

This update includes improved logging, faster UI monitoring, and stability enhancements across all supported platforms.

Updated Command-Line Interface (CLI)​

The Custom Widgets CLI is designed to automate repetitive tasks in Qt development. It now supports file monitoring, UI conversion, Designer launching, and project setup — all in one tool.

Monitor UI Files for Changes​

Custom_Widgets --monitor-ui path/to/file.ui --qt-library PySide6

Automatically converts .ui files to Python when changes are detected.

Convert UI Files to Python​

Custom_Widgets --convert-ui path/to/file.ui --qt-library PySide6

Instantly converts .ui files to .py while preserving all custom widget imports.

Launch Designer​

Custom_Widgets --start-designer --plugins

Opens Qt Designer with Custom Widgets automatically loaded.

Create a New Project​

Custom_Widgets --create-project

Sets up a ready-to-use project structure for developing with Qt Custom Widgets.

For detailed command usage:

Custom_Widgets --help

Upgrade Now​

To upgrade to version 2.0.1, run:

pip install --upgrade QT-PyQt-PySide-Custom-Widgets

Or visit the official PyPI page: https://pypi.org/project/QT-PyQt-PySide-Custom-Widgets/