From f59f881798132f00ca0254b2fbdb38608d337f75 Mon Sep 17 00:00:00 2001 From: Alex Huszagh Date: Sun, 1 May 2022 10:08:16 -0500 Subject: [PATCH] Update README documentation for plugins/overview. Update the overview description to simplify and better describe the stylesheet overview. Update the testing documentation. Add a section for plugins with links to the plugin code. --- README.md | 44 ++++++++++++++++++++++++++++++++++++-------- extension/README.md | 6 +++--- test/ui.py | 8 ++++---- 3 files changed, 43 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 9040730..3ecc84f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ BreezeStyleSheets Configurable Breeze and BreezeDark-like stylesheets for Qt Applications. -This stylesheet aims to be similar across all platforms, and provide a nice UI for different DPIs (as determined by the default font size, or using the screen scale factor). This is currently under work for scaling to multiple different DPIs and font sizes. +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 plugin 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** @@ -15,6 +15,7 @@ This stylesheet aims to be similar across all platforms, and provide a nice UI f - [PyQt5 Installation](#pyqt5-installation) - [PyQt6 Installation](#pyqt6-installation) - [Features](#features) + - [Plugins](#plugins) - [Extending Stylesheets](#extending-stylesheets) - [Known Issues](#known-issues) - [Debugging](#debugging) @@ -392,12 +393,12 @@ def main(): - Cross-platform icon packs for standard icons. - Extensible stylesheets: add your own plugins or rules and automatically configure them using the same configuration syntax. -**Plugins** +## Plugins The supported plugins can be found in the [extensions](/extension/README.md) directory and include theme support for: -- Advanced Docking System -- QDockWidget Tooltips -- Complete Standard Icon Set +- [Advanced Docking System](/extension/README.md#advanced-docking-system) +- [QDockWidget Tooltips](/extension/README.md#qdockwidget-tooltips) +- [Complete Standard Icon Set](/extension/README.md#standard-icons) # Extending Stylesheets @@ -445,13 +446,40 @@ python configure.py --compiled-resource breeze_resources.py ## Testing -In order to test your changes, first run the tests using the appropriate widget in [ui.py](test/ui.py) (see the options for `stylesheet`, `widget`, `font-size`, and `font-family`), and then run the tests with the complete UI in `example.py`. If the widget you fixed the style for does not exist in `example.py`, please add it. +The unittest suite is [ui.py](test/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](/example/widgets.py). If the widget you fixed the style for does not exist in the test suite or [widgets.py](/example/widgets.py), please add it. ```bash # Test all widgets -python test/ui.py --stylesheet $theme +$ python test/ui.py --stylesheet $theme # Test only a single widget. -python test/ui.py --widget $widget --stylesheet $theme +$ python test/ui.py --widget $widget --stylesheet $theme +# Get the help options. +$ python test/ui.py --help +usage: ui.py [-h] [--widget WIDGET] [--stylesheet STYLESHEET] [--style STYLE] + [--font-size FONT_SIZE] [--font-family FONT_FAMILY] [--width WIDTH] + [--height HEIGHT] [--alignment ALIGNMENT] [--compress] [--scale SCALE] [--pyqt6] + [--use-x11] + +Configurations for the Qt application. + +options: + -h, --help show this help message and exit + --widget WIDGET widget to test. can provide `all` to test all widgets + --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 + --width WIDTH the window width + --height HEIGHT the window height + --alignment ALIGNMENT + the layout alignment + --compress add stretch on both sides + --scale SCALE scale factor for the UI + --pyqt6 use PyQt6 rather than PyQt5. + --use-x11 force the use of x11 on compatible systems ``` To see the complete list of Qt widgets covered by the unittests, see [Test Coverage](Test%20Coverage.md). diff --git a/extension/README.md b/extension/README.md index 48ea76e..dd4ee57 100644 --- a/extension/README.md +++ b/extension/README.md @@ -9,7 +9,7 @@ Furthermore, this simplifies making local, application-specific changes, without # Pre-Packaged Extensions -**Advanced Docking System** +### Advanced Docking System This extension adds support for the [Advanced Docking System](https://github.com/githubuser0xFFFF/Qt-Advanced-Docking-System). This comes with styles for the dock manager to create a consistent theme between the main stylesheet and the docking system. @@ -53,7 +53,7 @@ And make sure to [disable](https://github.com/githubuser0xFFFF/Qt-Advanced-Docki /> -**QDockWidget Tooltips** +### QDockWidget Tooltips This extension adds tooltips to QDockWidget's float and close buttons. @@ -71,7 +71,7 @@ python configure.py --extensions=dock-tooltips /> -**Standard Icons** +### Standard Icons This extension adds a complete set of standard icons to override the Qt defaults. Please reference [standard_icons.py](/example/standard_icons.py) for an example of how to override these icons. These cannot be overwritten solely using a stylesheet, so you must provide your own subclass of `QCommonStyle` and override the `standardIcon` method. diff --git a/test/ui.py b/test/ui.py index 75f2687..c295c3d 100644 --- a/test/ui.py +++ b/test/ui.py @@ -41,15 +41,15 @@ home = os.path.dirname(tests_dir) dist = os.path.join(home, 'dist') # Create our arguments. -parser = argparse.ArgumentParser(description='Configurations for the Qt5 application.') +parser = argparse.ArgumentParser(description='Configurations for the Qt application.') parser.add_argument( '--widget', - help='widget to test. can provide `all` to test all', + help='widget to test. can provide `all` to test all widgets', default='all' ) parser.add_argument( '--stylesheet', - help='stylesheet name', + help='stylesheet name (`dark`, `light`, `native`, ...)', default='native' ) # Know working styles include: @@ -57,7 +57,7 @@ parser.add_argument( # 2. Windows parser.add_argument( '--style', - help='application style, which is different than the stylesheet', + help='application style (`Fusion`, `Windows`, `native`, ...)', default='native' ) parser.add_argument(