BreezeStyleSheets

Configurable Breeze and BreezeDark-like stylesheets for Qt Applications.

BreezeStyleSheets is a set of beautiful light and dark stylesheets that render consistently across platforms, including high DPI screens. Each stylesheet is generated from a theme file and can be extended with a extension system, simplifying the generation custom stylesheets for your application. The stylesheets are comprehensively tested with most Qt widgets and widget properties, providing a consistent, stylish feel on any platform, including different operating systems, desktop environments, and Qt versions.

Table of Contents

1. Gallery
2. Getting Started
   • Building Styles
   • Python Installation
   • CMake Installation
   • QMake Installation
3. Examples
4. Features
   • Extensions
5. Customization
6. Extending Stylesheets
7. Debugging
8. Development Guide
   • Git Hooks
   • Configuring Styles
   • Testing
   • Linting and Type Checks
   • Distribution Files
   • Git Ignore
9. Known Issues and Workarounds
10. License
11. Contributing
12. Acknowledgements
13. Contact

Gallery

Breeze/BreezeDark

Example user interface using the Breeze and BreezeDark stylesheets side-by-side.

Alternative themes - Change QTableWidget hover behavior to highlight whole row, instead of individual cells.

For an extensive view of screenshots of the theme, see the gallery.

Getting Started

Here are detailed instructions on how to install Breeze Style Sheets for a variety of build systems and programming languages. This will require a Qt installation with QtCore, QtGui, QtWidgets, and QtSvg installed.

Building Styles

By default, BreezeStyleSheets comes with the dark and light themes pre-built in the resources directory. In order to build all pre-packaged themes including PyQt5 and PyQt6 support, run:

# choose only the frameworks you want
frameworks=("pyqt5" "pyqt6" "pyside2" "pyside6")
for framework in "${frameworks[@]}"; do
    python configure.py --styles=all --extensions=all --qt-framework "${framework}" \
        --resource breeze.qrc --compiled-resource "breeze_${framework}.py"
done

All generated themes will be in the dist subdirectory, and the compiled Python resource(s) will be in resources/breeze_{framework}.py (for example, resources/breeze_pyqt5.py). Note that using the --compiled-resource flag requires the correct RCC to be installed for the Qt framework (see Python Installation for the required RCC).

Python Installation

To compile the stylesheet for use with PyQt5, PyQt6, PySide2 or PySide6, ensure you configure with the --compiled-resource flag (which requires the rcc executable for your chosen framework to be installed - see below for details). The compiled resource Python file now contains all the stylesheet data. To load and set the stylesheet in a PyQt5/6 or PySide2/6 application, import that file, load the contents using QFile and read the data. For example, to load BreezeDark, first configure using:

python configure.py --compiled-resource breeze_resources.py

Then load the stylesheet and run the application using:

from PyQt5 import QtWidgets
from PyQt5.QtCore import QFile, QTextStream
# This must match the name of the file and be in the Python search path.
# To modify the search path, add the directory containing the file to `sys.path`.
import breeze_resources


def main():
    app = QtWidgets.QApplication(sys.argv)

    # set stylesheet
    file = QFile(":/dark/stylesheet.qss")
    file.open(QFile.ReadOnly | QFile.Text)
    stream = QTextStream(file)
    app.setStyleSheet(stream.readAll())

    # code goes here

    app.exec_()

The required Qt resource compilers (RCC) for each framework are: - PyQt5: pyrcc5 - PyQt6: pyside6-rcc (requires PySide6 installed) - PySide2: pyside2-rcc (requires Python.10 or earlier) - PySide6: pyside6-rcc

You can also use the pre-compiled resources in the resources directory.

CMake Installation

Using CMake, you can download, configure, and compile the resources as part part of the build process. The following configurations are provided by @ruilvo. You can see a full example in example. First, save the following as breeze.cmake.

# Setup Qt: this works with both Qt5 and Qt6
# NOTE: We use cached strings to specify the options for these.
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)

find_package(
  ${QT_VERSION}
  COMPONENTS Core Gui Widgets
  REQUIRED)
# -------------------

# Get Python to compile the stylesheets.
# Fetch the repository, configure, compile the stylesheets.
find_package(Python COMPONENTS Interpreter)

include(FetchContent)

set(FETCHCONTENT_QUIET OFF CACHE BOOL "Silence fetch content" FORCE)

FetchContent_Declare(
  breeze_stylesheets
  GIT_REPOSITORY https://github.com/Alexhuszagh/BreezeStyleSheets.git
  GIT_TAG origin/main
  GIT_PROGRESS ON
  GIT_SHALLOW 1
  USES_TERMINAL_DOWNLOAD TRUE)

FetchContent_GetProperties(breeze_stylesheets)
if(NOT breeze_stylesheets_POPULATED)
  FetchContent_Populate(breeze_stylesheets)

  add_library(breeze STATIC "${breeze_stylesheets_SOURCE_DIR}/dist/breeze.qrc")

  add_custom_target(
    run_python_breeze ALL
    COMMAND ${Python_EXECUTABLE} configure.py --extensions=${BREEZE_EXTENSIONS}
            --styles=${BREEZE_STYLES} --resource breeze.qrc
    WORKING_DIRECTORY ${breeze_stylesheets_SOURCE_DIR}
    BYPRODUCTS "${breeze_stylesheets_SOURCE_DIR}/dist/breeze.qrc"
    COMMENT "Generating themes")

  add_dependencies(breeze run_python_breeze)
endif()

Next, make sure the path to breeze.cmake is in your module search path, and add the following to your CMakeLists.txt:

set(QT_VERSION Qt5 CACHE STRING "The Qt version framework to use (Qt5 or Qt6).")
set(BREEZE_EXTENSIONS all CACHE STRING "The extensions to include in our stylesheets.")
set(BREEZE_STYLES all CACHE STRING "The styles to include in our stylesheets.")

include(breeze)

add_executable(myapp WIN32 MACOSX_BUNDLE "main.cpp")
target_link_libraries(myapp PRIVATE Qt${QT_VERSION_MAJOR}::Widgets breeze)

And then in your application start point, add the following:

#include <QApplication>
#include <QFile>
#include <QTextStream>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // Need to initialize the resource, since we're using an external
    // build system and this isn't automatically handled by CMake.
    Q_INIT_RESOURCE(breeze);
    QFile file(":/dark/stylesheet.qss");
    file.open(QFile::ReadOnly | QFile::Text);
    QTextStream stream(&file);
    app.setStyleSheet(stream.readAll());

    // code goes here

    return app.exec();
}

QMake Installation

Copy the contents of the dist subdirectory into your project directory and add the qrc file to your project file.

For example:

TARGET = app
SOURCES = main.cpp
RESOURCES = breeze.qrc

To load the stylesheet in C++, load the file using QFile and read the data. For example, to load BreezeDark, run:

#include <QApplication>
#include <QFile>
#include <QTextStream>


int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // set stylesheet
    QFile file(":/dark/stylesheet.qss");
    file.open(QFile::ReadOnly | QFile::Text);
    QTextStream stream(&file);
    app.setStyleSheet(stream.readAll());

    // code goes here

    return app.exec();
}

Examples

Many examples of widgets using custom themes, including with the Advanced Docking System, custom icons, and titlebars can be found in the example directory.

The support stylesheets include: - dark - light - auto - native (the system native theme)

And any -purple, -green, etc. variants can also be used. auto will automatically detect if the system theme is light or dark and select the correct theme accordingly. A recipe for a cross-platform way to detect the correct theme in Python or C++ is shown in our System Theme Detection.

Features

• Complete stylesheet for all Qt widgets, including esoteric widgets like QCalendarWidget.
• Customizable, beautiful light and dark themes.
• Cross-platform icon packs for standard icons.
• Extensible stylesheets: add your own extensions or rules and automatically configure them using the same configuration syntax.

Extensions

The supported extensions can be found in the extensions directory and include theme support for: - Advanced Docking System - QDockWidget Tooltips - Complete Standard Icon Set

Customization

It's easy to design your own themes using configure.py. First, add the styles you want into theme, then run configure with a list of styles you want to include.

Theme

Here is a sample theme, with the color descriptions annotated. Please note that although there are nearly 40 possibilities, for most applications, you should use less than 20, and ~10 different hues.

``jsonc // NOTE: This is a custom JSON file, where lines leading // with//` are removed. No other comments are valid. { // Main foreground color. "foreground": "#eff0f1", // Lighter foreground color for selected items. "foreground-light": "#ffffff", // Main background color. "background": "#31363b", // Alternate background color for styles. "background:alternate": "#31363b", // Main color to highlight widgets, such as on hover events. "highlight": "#3daee9", // Color for selected widgets so hover events can change widget color. "highlight:dark": "#2a79a3", // Alternate highlight color for hovered widgets in QAbstractItemViews. "highlight:alternate": "#369cd1", // Main midtone color, such as for borders. "midtone": "#76797c", // Lighter color for midtones, such as for certain disabled widgets. "midtone:light": "#b0b0b0", // Darker midtone, such as for the background of QPushButton and QSlider. "midtone:dark": "#626568", // Lighter midtone for separator hover events. "midtone:hover": "#8a8d8f", // Color for checked widgets in QAbstractItemViews. "view:checked": "#334e5e", // Hover background color in QAbstractItemViews. // This should be fairly transparent. "view:hover": "rgba(61, 173, 232, 0.1)", // Background for a horizontal QToolBar. "toolbar:horizontal:background": "#31363b", // Background for a vertical QToolBar. "toolbar:vertical:background": "#31363b", // Background color for the corner widget in a QAbstractItemView. "view:corner": "#31363b", // Border color between items in a QHeaderView. "view:header:border": "#76797c", // Background color for a QHeaderView. "view:header": "#31363b", // Border color Between items in a QAbstractItemView. "view:border": "#31363b", // Background for QAbstractItemViews. "view:background": "#1d2023", // Background for widgets with text input. "text:background": "#1d2023", // Background for the currently selected tab. "tab:background:selected": "#31363b", // Background for non-selected tabs. "tab:background": "#2c3034", // Color for the branch/arrow icons in a QTreeView. "tree": "#afafaf", // Color for the chunk of a QProgressBar, the active groove // of a QSlider, and the border of a hovered QSlider handle. "slider:foreground": "#3daee9", // Background color for the handle of a QSlider. "slider:handle:background": "#1d2023", // Color for a disabled menubar/menu item. "menu:disabled": "#76797c", // Color for a checked/hovered QCheckBox or QRadioButton. "checkbox:light": "#58d3ff", // Color for a disabled or unchecked/unhovered QCheckBox or QRadioButton. "checkbox:disabled": "#c8c9ca", // Color for the handle of a scrollbar. Due to limitations of // Qt stylesheets, any handle of a scrollbar must be treated // like it's hovered. "scrollbar:hover": "#3daee9", // Background for a non-hovered scrollbar. "scrollbar:background": "#1d2023", // Background for a hovered scrollbar. "scrollbar:background:hover": "#76797c", // Default background for a QPushButton. "button:background": "#31363b", // Background for a pressed QPushButton. "button:background:pressed": "#454a4f", // Border for a non-hovered QPushButton. "button:border": "#76797c", // Background for a disabled QPushButton, or fallthrough // for disabled QWidgets. "button:disabled": "#454545", // Color of a dock/tab close icon when hovered. "close:hover": "#b37979", /