GitHub - Alexhuszagh/BreezeStyleSheets: Breeze/BreezeDark-like Qt StyleSheets (original) (raw)

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
  3. Examples
  4. Features
  5. Customization
  6. Extending Stylesheets
  7. Debugging
  8. Development Guide
  9. Known Issues and Workarounds
  10. License
  11. Contributing
  12. Acknowledgements
  13. Contact

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. Also changes background color of light themes to a light gray and applies theme color to radio buttons and checkboxes.

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:

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 Svg 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 PythonEXECUTABLEconfigure.py−−extensions={Python_EXECUTABLE} configure.py --extensions=PythonE​XECUTABLEconfigure.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 #include #include

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();

}

If you get an issue with copy relocations against a non-copyable protected symbol, ensure the POSITION_INDEPENDENT_CODE is set to ON. For the example above, add the following line:

set_property(TARGET breeze PROPERTY POSITION_INDEPENDENT_CODE ON)

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 #include #include

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();

}

Qt Components

If using a minimal installation of Qt, ensure QtSvg is installed (along with QtCore, QtGui, and QtWidgets). SVG support is required to correctly display the widget icons.

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:

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

Extensions

The supported extensions can be found in the extensions directory and include theme support for:

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.

Once you've saved your custom theme, you can then build the stylesheet, icons, and resource file with:

python configure.py --styles=dark,light, --resource custom.qrc

Then, you can use custom.qrc, along with the generated icons and stylesheets in each folder, in place of breeze.qrc for any style.

The --styles command flag takes a comma-separated list of values, or all, which will configure every theme present in the themes directory.

Generating Colors

As a reference point, see the pre-generated themes. In general, to create a good theme, modify only the highlight colors (blues, greens, purples) to a new color, such that the saturation and lightness stay the same (only the hue changes). For example, the color rgba(51, 164, 223, 0.5) becomes rgba(164, 51, 223, 0.5).

Adding Extensions

We also allow customizable extensions to extend the default stylesheets with additional style rules, using the colors defined in your theme. This also enables the integration of third-party Qt extensions/widgets into the generated stylesheets.

For example, to configure with extensions for the Advanced Docking System, run:

python configure.py --extensions=advanced-docking-system --resource custom.qrc

Like with styles, --extensions takes a comma-separated list of values, or all, which will add every extension present in the extensions directory. For a detailed introduction to creating your own extensions, see the extensions tutorial.

Extending Stylesheets

There are some limitations of using Qt stylesheets in general, which cannot be solved by stylesheets. To get more fine-grained style control, you should subclass QCommonStyle:

class ApplicationStyle: public QCommonStyle { ... }

The limitations of stylesheets include:

For an example of using QCommonStyle to override standard icons in a PyQt application, see standard_icons.py. An extensive reference can be found here. A reference of QStyle, and the default styles Qt provides can be found here.

Debugging

Have an issue with the styles? Here's a few suggestions, prior to filing a bug report:

Development Guide

Git Hooks

Contributors to BreezeStylesheets should make use of vcs and scripts to both install Git hooks and run local tests and typechecking. After cloning the repository, developers should first install a pre-commit hook, to ensure their code is formatted and linted prior to commiting:

python vcs.py --install-hooks

Configuring Styles

To configure the assets and the stylesheets, run python configure.py. To compile the assets and stylesheets for PyQt5, ensure pyrcc5 is installed (for other frameworks, see Python Installation for the correct RCC) and run:

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

Testing

The unittest suite is ui.py. By default, the suite runs every test, so to test changes to a specific widget, pass the --widget $widget flag. To test other configurations, see the options for --stylesheet, --widget, --font-size, and --font-family, and then run the tests with the complete UI in widgets.py. If the widget you fixed the style for does not exist in the test suite or widgets.py, please add it.

Test all widgets

$ python test/ui.py --stylesheet $theme

Test only a single widget.

$ python test/ui.py --widget widget−−stylesheetwidget --stylesheet widget−−stylesheettheme

Get the help options.

$ python test/ui.py --help usage: ui.py [-h] [--stylesheet STYLESHEET] [--style STYLE] [--font-size FONT_SIZE] [--font-family FONT_FAMILY] [--scale SCALE] [--qt-framework {pyqt5,pyqt6,pyside2,pyside6}] [--use-x11] [--widget WIDGET] [--width WIDTH] [--height HEIGHT] [--alignment ALIGNMENT] [--compress] [--print-tests] [--start START]

Configurations for the Qt5 application.

options: -h, --help show this help message and exit --stylesheet STYLESHEET stylesheet name (dark, light, native, ...) --style STYLE application style (Fusion, Windows, native, ...) --font-size FONT_SIZE font size for the application --font-family FONT_FAMILY the font family --scale SCALE scale factor for the UI --qt-framework {pyqt5,pyqt6,pyside2,pyside6} target framework to build for. Default = pyqt5. Note: building for PyQt6 requires PySide6-rcc to be installed. --use-x11 force the use of x11 on compatible systems. --widget WIDGET widget to test. can provide all to test all widgets --width WIDTH the window width --height HEIGHT the window height --alignment ALIGNMENT the layout alignment --compress add stretch on both sides --print-tests print all available tests (widget names). --start START test widget to start at.

Get a complete list of available tests.

$ python test/ui.py --print-tests aero_wizard all_focus_tree alpha_colordialog ... wizard yes_button

To see the complete list of Qt widgets covered by the unittests, see Test Coverage.

Linting and Type Checks

You can check code quality using static typecheckers and code linters.

format python code to a standard style.

requires black and isort to be installed.

scripts/fmt.sh

run linters and static typecheckers

requires pylint, pyright, and flake8 to be installed

scripts/lint.sh

check if the system can automatically determine the theme

on windows, this requires winrt-Windows.UI.ViewManagement

and winrt-Windows.UI to be installed.

scripts/theme.sh

run more involved, comprehensive tests. these assume a Linux

environment and detail the install scripts to use them.

scripts/cmake.sh scripts/headless.sh

Distribution Files

When pushing changes, only the light and dark themes should be configured, without any extensions. To reset the built resource files to the defaults (this requires the correct RCC to be installed), run:

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

If no changes are being made to the icons or stylesheets, you may want to ensure that the dist directory is assumed to be unchanged in git, no longer tracking changes to these files. You can turn tracking distribution files off with:

python vcs.py --no-track-dist

To turn back on tracking, run:

python vcs.py --track-dist

Git Ignore

Note that the .gitignore is auto-generated via vcs.py, and the scripts to track or untrack distribution files turn off .gitignore tracking. Any changes should be made in vcs.py, and ensure that .gitignore is tracked, and commit any changes:

python vcs.py --track-gitignore git add .gitignore git commit -m "..."

Known Issues and Workarounds

For known issues and workarounds, see issues.

License

MIT, see license.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in BreezeStyleSheets by you shall be licensed under the MIT license without any additional terms or conditions. See the changelog for changes and contributors to the project.

Acknowledgements

BreezeStyleSheets is a fork of QDarkStyleSheet. Some of the icons are modified from Material UI and Material Design Icons (both of which use an Apache 2.0 license), and are redistributed under the MIT license.

Major contributions to the project have been made by:

Contact

Email: ahuszagh@gmail.com