QDarkStyleSheet Documentation

The qdarkstyle package is organized into several subpackages and submodules for managing themes and utilities:

Subpackages:

• qdarkstyle.dark: Dark theme implementations.
• qdarkstyle.light: Light theme implementations.
• qdarkstyle.example: Example usage and demonstrations.
• qdarkstyle.utils: Utility functions for the package.

Submodules:

• qdarkstyle.__main__: Main entry point for the package.
• qdarkstyle.colorsystem: Logic for handling color systems.
• qdarkstyle.palette: Logic for managing color palettes.

If you are making frequent changes to the stylesheet (.scss files) or UI files, use the run_ui_css_edition.py script. This script creates a loop that automatically restarts the application and processes both UI and CSS files, making the iteration process much faster.

python scripts/run_ui_css_edition.py

When you modify the stylesheet files in qdarkstyle/qss/_styles.scss, you must recompile the QRC files to update the generated resources. Use the qdarkstyle.utils module to generate:

• Resource files (images)
• style.qrc
• _variables.scss
• style.qss
• style_rc.py (for each palette)

python qdarkstyle\utils

To install the latest stable version of the qdarkstyle package for Python, use pip.

pip install qdarkstyle

The color system provides scales for themes to draw from. Each color scale uses a range of values from 0 (black #000000) to 150 (white #ffffff). The assigned number estimates the lightness or darkness of the color.

Accessibility Guidelines

When designing themes or selecting color combinations for interactive elements, text, or important information, ensure that overlapping colors have a difference of at least 20 in their scale values. Depending on the specific colors used, higher contrast may be required to meet accessibility standards for color blindness or general readability.

To use the stylesheet in a C++ Qt application:

1. Copy the following files from the repository to your application directory, maintaining the directory hierarchy (replace THEME with dark or light):

   • qdarkstyle/THEME/THEMEstyle.qss
   • qdarkstyle/THEME/THEMEstyle.qrc
   • qdarkstyle/THEME/rc/ (the entire directory)

2. Add the .qrc file to your .pro file: RESOURCES += qdarkstyle/THEME/THEMEstyle.qrc

3. Load the stylesheet using the resource path (starting with :).

QFile f(":qdarkstyle/THEME/THEMEstyle.qss");
if (!f.exists())   {
    printf("Unable to set stylesheet, file not found\n");
}
else   {
    f.open(QFile::ReadOnly | QFile::Text);
    QTextStream ts(&f);
    qApp->setStyleSheet(ts.readAll());
}

The project includes a comprehensive example application built at runtime via qdarkstyle.example. This application contains almost all common Qt widgets, which you can use to test your stylesheet changes. The UI is split into several .ui files located in qdarkstyle/example/ui/:

• dw_buttons.ui: All button types
• dw_containers_no_tabs.ui: Containers (excluding tabs)
• dw_containers_tabs.ui: Containers with tabs
• dw_displays.ui: Display widgets
• dw_inputs_fields.ui: Input fields
• dw_inputs_no_fields.ui: Inputs without fields
• dw_views.ui: View widgets
• dw_widgets.ui: General widgets
• mw_menus.ui: Main window with menus and toolbars

Note: dw stands for dock widget and mw for main window.

python qdarkstyle\example

To develop on QDarkStyle, fork the repository, clone it, and checkout the develop branch. It is highly recommended to use a virtual environment.

Using virtualenv:

# Create and activate environment
virtualenv ~/.venv
. ~/.venv/bin/activate

# Install dependencies in editable mode
pip install -e .[develop]

Using conda:

# Create environment with python 3.8
conda create -n my-dev-env -c conda-forge python=3.8
conda activate my-dev-env

# Remove existing installation if present
conda remove --force qdarkstyle

# Install required tools and dependencies
conda install -c conda-forge watchdog qtsass
pip install -e .[develop]

The package includes a command-line tool to view the different themes (dark, light, or none) via the qdarkstyle.example script. Requires PySide2 or PyQt5 to be installed.

# dark theme example
$ qdarkstyle.example --palette=dark

# light theme example
$ qdarkstyle.example --palette=light

# no theme/style sheet applied
$ qdarkstyle.example --palette=none

# check all options included
$ qdarkstyle.example --help