initial fluent-widgets ui

docs/source/_static/js/fancybox.js

@@ -0,0 +1,35 @@
+function buildFancybox() {
+    $(".article-container section img").unwrap();
+    let images = Array.from($('.article-container section img'));
+    if (!images.length) return;
+
+    images.forEach(el => {
+        const src = $(el).attr("src");
+        const alt = $(el).attr("alt") || '';
+        $(el).after(`<a href="${src}" data-download-src="${src}" data-caption="${alt}" data-fancybox="gallery"><img src="${src}"/></a>`);
+        $(el).remove();
+    });
+
+    window.Fancybox.bind('[data-fancybox="gallery"]', {
+        Toolbar: {
+            display: [
+                "counter",
+                "zoom",
+                "slideshow",
+                "fullscreen",
+                "download",
+                "thumbs",
+                "close",
+            ],
+        },
+        Image: {
+            zoom: false,
+        },
+        showClass: "fancybox-zoomIn",
+        hideClass: "fancybox-zoomOut",
+    });
+
+}
+
+
+buildFancybox();

docs/source/conf.py

@@ -0,0 +1,53 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'PyQt-Fluent-Widgets'
+copyright = '2023, zhiyiYo'
+author = 'zhiyiYo'
+release = 'v0.4.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+source_parsers = {
+    '.md': 'recommonmark.parser.CommonMarkParser',
+}
+source_suffix = ['.rst', '.md']
+extensions = ['recommonmark', 'sphinx_markdown_tables']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    "sidebar_hide_name": False,
+}
+
+html_show_sourcelink = True
+html_title = "PyQt-Fluent-Widgets"
+html_favicon = "_static/logo.png"
+html_css_files = [
+    'css/fancybox.css',
+    'css/custom.css',
+]
+html_js_files = [
+    'js/fancybox.umd.js',
+    'js/fancybox.js',
+]
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True

docs/source/designer.rst

@@ -0,0 +1,69 @@
+
+Designer
+--------
+
+In Qt Designer, there are two ways to use PyQt-Fluent-Widgets.
+
+Promoting widget
+^^^^^^^^^^^^^^^^
+
+Right click on a widget, select the ``Promote to ...`` of context menu.
+
+Promoting a widget indicates that it should be replaced with the specified subclass, in our case the ``qfluentwidgets.PushButton``.
+
+.. image:: ./_static/promote_context.jpg
+   :target: ./_static/promote_context.jpg
+   :alt:
+
+
+You will be presented with a dialog to specify the custom widget class the placeholder widget will become.
+
+The header file is the name of the Python module used to import the class, which is ``qfluentwidgets``. Specify ``PushButton`` as the class name of the widget to replace it with.
+
+.. image:: ./_static/promote_dialog.jpg
+   :target: ./_static/promote_dialog.jpg
+   :alt:
+
+
+Well, the widget is now promoted to fluent push button. But you won't be able to see any changes within Qt Designer. Save the window as ``mainwindow.ui`` and compile it to python code, you will see that the ``PushButton`` is imported from ``qfluentwidgets`` package.
+
+Using plugin
+^^^^^^^^^^^^
+
+1. create a virtual environment, ``conda`` is the recommended way.
+
+
+2. Activate virtual environment and run the following code in shell:
+
+   .. code-block:: sh
+
+      pip install PyQt-Fluent-Widget
+      pip install pyqt5-tools
+
+3. Download the full code from `PyQt-Fluent-Widgets Repo <https://github.com/zhiyiYo/PyQt-Fluent-Widgets>`_.
+
+4. Run ``python ./tools/designer.py`` to launch Qt Designer (You must use this way to launch Qt Designer).
+
+
+If everything goes smoothly, you will see all PyQt-Fluent-Widgets components in the sidebar of Qt Designer.
+If the startup fails or the components of PyQt-Fluent-Widgets cannot be seen, the solution can be found in `#196 <https://github.com/zhiyiYo/PyQt-Fluent-Widgets/issues/196>`_.
+
+.. image:: ./_static/Designer_plugin.jpg
+   :target: ./_static/Designer_plugin.jpg
+   :alt:
+
+
+The plugin for PySide6 is unstable and may not start QtDesigner successfully. It is recommended to use QtDesigner of PyQt5/6 to generate ui files.
+
+.. note:: PyQt5 must upgrade PyQt5-Frameless-Window to 0.2.7 in order to use the plugin, while PySide6 and PyQt6 do not need to upgrading to frameless packages. PySide2 does not support plugins, but you can use PyQt5's QtDesigner to generate ui files and then compile them into py files using uic.
+
+
+Complex example
+^^^^^^^^^^^^^^^
+Here is an example that uses a side navigation bar to implement multiple sub-interfaces window.
+
+.. raw:: html
+
+   <div style="position: relative; padding: 30% 45%;">
+      <iframe style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" src="https://player.bilibili.com/player.html?cid=1193201502&aid=530806716&page=1&as_wide=1&high_quality=1&danmaku=0" frameborder="no" scrolling="no" allowfullscreen="true"></iframe>
+   </div>

docs/source/gallery.md

@@ -0,0 +1,62 @@
+## Gallery
+
+### Basic input
+#### Button
+![](./_static/gallery/button.gif)
+
+#### Check Box
+![](./_static/gallery/check_box.gif)
+
+#### Combo Box
+![](./_static/gallery/combo_box.gif)
+
+#### Radio Button
+![](./_static/gallery/radio_button.gif)
+
+#### Switch Button
+![](./_static/gallery/switch_button.gif)
+
+#### Slider
+![](./_static/gallery/slider.gif)
+
+#### Hollow Handle Slider
+![](./_static/gallery/hollow_handle_slider.gif)
+
+
+### Dialogs
+#### Color Dialog
+![](./_static/gallery/color_dialog.gif)
+
+#### Dialog
+![](./_static/gallery/dialog.gif)
+
+#### Message Box
+![](./_static/gallery/message_box.gif)
+
+#### Win10 Style Message Dialog
+![](./_static/gallery/dialog_with_mask.gif)
+
+#### Folder List Dialog
+![](./_static/gallery/folder_list_dialog.gif)
+
+
+### Menus
+![](./_static/gallery/round_menu.gif)
+
+### Flow Layout
+![](./_static/gallery/flow_layout.gif)
+
+### Navigation
+![](./_static/gallery/navigation.gif)
+
+### Status & info
+#### State Tool Tip
+![](./_static/gallery/state_tool_tip.gif)
+
+#### Tool Tip
+![](./_static/gallery/tool_tip.gif)
+
+
+### Material
+#### Acrylic Label
+<img width="60%" src="./_static/gallery/acrylic_label.png"/>

docs/source/icon.md

@@ -0,0 +1,19 @@
+## Icon
+Many widgets need icons, if you want PyQt-Fluent-Widgets change your icons automatically when the theme changes, then you can inherit `FluentIconBase` and overide `path()` method. Here is an example:
+
+```python
+from enum import Enum
+
+from qfluentwidgets import getIconColor, Theme, FluentIconBase
+
+
+class MyFluentIcon(FluentIconBase, Enum):
+    """ Custom icons """
+
+    ADD = "Add"
+    CUT = "Cut"
+    COPY = "Copy"
+
+    def path(self, theme=Theme.AUTO):
+        return f':/icons/{self.value}_{getIconColor(theme)}.svg'
+```

docs/source/index.rst

@@ -0,0 +1,55 @@
+.. PyQt-Fluent-Widgets documentation master file, created by
+   sphinx-quickstart on Tue Jan 17 15:31:54 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. raw:: html
+
+   <p align="center">
+      <img width="18%" align="center" src="./_static/logo.png" alt="logo">
+   </p>
+
+   <h1 align="center">
+      PyQt-Fluent-Widgets
+   </h1>
+
+   <hr/>
+
+   <p align="center">
+      A fluent design widgets library based on PyQt5
+   </p>
+
+   <p align="center">
+      <a style="text-decoration:none">
+         <img src="https://img.shields.io/badge/Platform-Win32%20|%20Linux%20|%20macOS-blue?color=#4ec820" alt="Platform Win32 | Linux | macOS"/>
+      </a>
+
+      <a style="text-decoration:none">
+         <img src="https://static.pepy.tech/personalized-badge/pyqt-fluent-widgets?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=Downloads" alt="Download"/>
+      </a>
+
+      <a style="text-decoration:none">
+         <img src="https://img.shields.io/badge/License-LGPLv3-blue?color=#4ec820" alt="LGPLv3"/>
+      </a>
+   </p>
+
+   <p align="center">
+      <img src="./_static/Interface.jpg" alt="Interface">
+   </p>
+
+
+Welcome to PyQt-Fluent-Widgets's document!
+===============================================
+This document will show you all the features of PyQt-Fluent-Widgets and the best practice of it.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   quick-start
+   settings
+   theme
+   navigation
+   icon
+   gallery
+   see-also

docs/source/navigation.md

@@ -0,0 +1,104 @@
+## Navigation
+### Structure
+
+PyQt Fluent Widgets provides a side navigation class `NavigationInterface`. You can use it with `QStackWidget` and put them in `QHBoxLayout`. Examples are available at https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/master/examples/navigation2.
+
+![](_static/NavigationInterface_Structure.jpg)
+
+`NavigationInterface` contains `NavigationPanel` which is used to place navigation menu items. All navigation menu items should inherit from `NavigationWidget` and you can add them to the panel by calling `NavigationInterface.addWidget()` or `NavigationPanel.addWidget()`. PyQt-Fluent-Widgets implements subclass `NavigationPushButton` and provides a convenient method `NavigationInterface.addItem()` to add it to the panel.
+
+If you want to customize a navigation menu item, you should inherit the `NavigationWidget` and rewrite its `paintEvent()` and `setCompacted()`(optional). Here an example shows how to create an avatar item.
+```python
+from qfluentwidgets import NavigationWidget
+
+
+class AvatarWidget(NavigationWidget):
+    """ Avatar widget """
+
+    def __init__(self, parent=None):
+        super().__init__(isSelectable=False, parent=parent)
+        self.avatar = QImage('resource/shoko.png').scaled(
+            24, 24, Qt.KeepAspectRatio, Qt.SmoothTransformation)
+
+    def paintEvent(self, e):
+        painter = QPainter(self)
+        painter.setRenderHints(
+            QPainter.SmoothPixmapTransform | QPainter.Antialiasing)
+
+        painter.setPen(Qt.NoPen)
+
+        if self.isPressed:
+            painter.setOpacity(0.7)
+
+        # draw background
+        if self.isEnter:
+            c = 255 if isDarkTheme() else 0
+            painter.setBrush(QColor(c, c, c, 10))
+            painter.drawRoundedRect(self.rect(), 5, 5)
+
+        # draw avatar
+        painter.setBrush(QBrush(self.avatar))
+        painter.translate(8, 6)
+        painter.drawEllipse(0, 0, 24, 24)
+        painter.translate(-8, -6)
+
+        if not self.isCompacted:
+            painter.setPen(Qt.white if isDarkTheme() else Qt.black)
+            font = QFont('Segoe UI')
+            font.setPixelSize(14)
+            painter.setFont(font)
+            painter.drawText(QRect(44, 0, 255, 36), Qt.AlignVCenter, 'zhiyiYo')
+```
+
+Now let's take a look at the parameters required for the `addWidget()` methed:
+
+```python
+def addWidget(
+    self,
+    routeKey: str,
+    widget: NavigationWidget,
+    onClick=None,
+    position=NavigationItemPosition.TOP,
+    tooltip: str = None,
+    parentRouteKey: str = None
+)
+```
+
+As you can see, this method requires four parameters:
+
+* `routeKey`: A unique name for the `widget` to be added. You can consider the sub interface in the `QStackWidget` as a web page, and the `routeKey` is the url of the web page. When you switch between sub interfaces, `NavigationPanel` will add a `routeKey` to the navigation history. When you click the return button, the `routeKey` at the top of the navigation history will pop up. If there are other `routeKeys` in the history at this time, PyQt-Fluent-Widgets will switch to the corresponding sub interface corresponding to current top `routeKey`. Otherwise, it will switch to the sub interface corresponding to `defaultRouteKey`, so you should call `NavigationInterface.setDefaultRouteKey()` before running app.
+* `widget`: The widget to be added to panel.
+* `onClick`: Slot function connected to the widget's `clicked` signal. If you want to switch sub interfaces when clicking `widget`t, it is recommended to write this slot function as `lambda: self.stackWidget.setCurrentWidget(self.xxxInterface) `.
+* `position`: Where to add the `widget` to the panel. The following values are available:
+  * `NavigationItemPosition.TOP`: add `widget` to the top layout of panel.
+  * `NavigationItemPosition.SCROLL`: add `widget` to the scroll layout of panel. You can scroll the widgets in scroll layout When there are too many menu items.
+  * `NavigationItemPosition.BOTTOM`: add `widget` to the bottom layout of panel.
+* `tooltip`: The tooltip of menu item.
+* `parentRouteKey`: The route key of parent menu item, the widget of parent item must be the instance of `NavigationTreeWidgetBase`
+
+### Display mode
+
+The navigation panel has four display modes:
+
+* `NavigationDisplayMode.EXPAND`: An expanded left pane on large window widths (1008px or greater).
+  ![](_static/NavigationInterface_Expanded.jpg)
+
+* `NavigationDisplayMode.COMPACT`: A left, icon-only, nav panel on medium window widths (1007px or less).
+  ![](_static/NavigationInterface_Compact.jpg)
+
+* `NavigationDisplayMode.MENU`: An expanded left menu (1007px or less).
+  ![](_static/NavigationInterface_Menu.jpg)
+
+* `NavigationDisplayMode.MINIMAL`: Only a menu button on small window widths (you should add and manage the menu button to main window by yourself like [navigation3](https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/master/examples/navigation3) does).
+
+If you call `NavigationInterface.setExpandWidth()`, the large window width (1008px) will change accordingly.
+
+
+### More examples
+Here is an another style of navigation interface, and its corresponding example program is available at https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/master/examples/navigation.
+
+![](_static/NavigationInterfacee.jpg)
+
+Minimal display mode navigation interface is available at [navigation3](https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/master/examples/navigation3).
+
+![](_static/NavigationInterface_Minimal.jpg)

docs/source/quick-start.rst

@@ -0,0 +1,34 @@
+Quick start
+-----------
+
+Install
+~~~~~~~
+
+To install lite version (``AcrylicLabel`` is not available) use pip:
+
+.. code:: shell
+
+   pip install PyQt-Fluent-Widgets -i https://pypi.org/simple/
+
+Or install full-featured version use pip:
+
+.. code:: shell
+
+   pip install "PyQt-Fluent-Widgets[full]" -i https://pypi.org/simple/
+
+If you are using PySide2, PySide6 or PyQt6, you can download the code in `PySide2 <https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/PySide2>`__, `PySide6 <https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/PySide6>`__ or `PyQt6 <https://github.com/zhiyiYo/PyQt-Fluent-Widgets/tree/PyQt6>`__ branch.
+
+.. warning:: Don't install PyQt-Fluent-Widgets, PyQt6-Fluent-Widgets, PySide2-Fluent-Widgets and PySide6-Fluent-Widgets at the same time, because their package names are all ``qfluentwidgets``.
+
+Run example
+~~~~~~~~~~~
+
+After installing PyQt-Fluent-Widgets package using pip, you can run any
+demo in the examples directory, for example:
+
+.. code:: python
+
+   cd examples/gallery
+   python demo.py
+
+.. note:: If you encounter ``ImportError: cannot import name 'XXX' from 'qfluentwidgets'``, it indicates that the package version you installed is too low. You can replace the mirror source with https://pypi.org/simple and reinstall again.

docs/source/see-also.md

@@ -0,0 +1,16 @@
+## See also
+
+Here are some projects that use PyQt-Fluent-Widgets:
+
+- [**zhiyiYo/QMaterialWidgets**: A material design widgets library based on PySide](https://github.com/zhiyiYo/QMaterialWidgets)
+  ![](https://raw.githubusercontent.com/zhiyiYo/QMaterialWidgets/master/docs/source/_static/Interface.jpg)
+
+<br>
+
+- [**zhiyiYo/Groove**: A cross-platform music player based on PyQt5](https://github.com/zhiyiYo/Groove)
+  ![](./_static/Groove音乐.jpg)
+
+<br>
+
+- [**zhiyiYo/Alpha-Gobang-Zero**: A gobang robot based on reinforcement learning](https://github.com/zhiyiYo/Alpha-Gobang-Zero)
+  ![](./_static/Alpha-Gobang-Zero.jpg)

docs/source/settings.md

@@ -0,0 +1,77 @@
+## Settings
+PyQt-Fluent-Widgets presents each configuration item as a `SettingCard` on the interface. The behavior of user on the `SettingCard` will change the value of the configuration item, and PyQt-Fluent-Widgets will update the configuration item to the json configuration file automatically.
+
+### Config
+PyQt-Fluent-Widgets uses the `ConfigItem` class to represent a configuration item and uses the `QConfig` class to read and write the value of `ConfigItem`. The `QConfig` class will automatically update the configuration file when the value of the `ConfigItem` changes.
+
+Since the value in config file may be manually modified by the user to an invalid value, PyQt-Fluent-Widgets use `ConfigValidator` and its subclass to verify and correct the config value.
+
+Json files only support string, boolean value, list and dict, for enumeration classes or `QColor`, we can't use `json.dump()` to write them directly into a json file, so PyQt-Fluent-Widgets provides `ConfigSerializer` and its subclass to serialize and deserialize config item from config file. For example, you can use `ColorSerializer` to serialize config items with `QColor` value type.
+
+`ConfigItem` has the following attributes:
+
+|  Attribute   |        Type        | Description                                                  |
+| :----------: | :----------------: | ------------------------------------------------------------ |
+|   `group`    |       `str`        | The group to which the config item belongs                   |
+|    `name`    |       `str`        | Name of config item                                          |
+|  `default`   |       `Any`        | The default value of config item, it will be used when the value in the config file is illegal |
+| `validator`  | `ConfigValidator`  | Config validator                                             |
+| `serializer` | `ConfigSerializer` | Config serializer                                            |
+|  `restart`   |       `bool`       | Whether to restart the application after updating value      |
+
+You should add config items to the class attribute of `QConfig` subclasss,  then use `qconfig.load()` to load config file, for example:
+
+```python
+class MvQuality(Enum):
+    """ MV quality enumeration class """
+
+    FULL_HD = "Full HD"
+    HD = "HD"
+    SD = "SD"
+    LD = "LD"
+
+    @staticmethod
+    def values():
+        return [q.value for q in MvQuality]
+
+
+class Config(QConfig):
+    """ Config of application """
+
+    # main window
+    enableAcrylic = ConfigItem("MainWindow", "EnableAcrylic", False, BoolValidator())
+    playBarColor = ColorConfigItem("MainWindow", "PlayBarColor", "#225C7F")
+    themeMode = OptionsConfigItem("MainWindow", "ThemeMode", "Light", OptionsValidator(["Light", "Dark", "Auto"]), restart=True)
+    recentPlaysNumber = RangeConfigItem("MainWindow", "RecentPlayNumbers", 300, RangeValidator(10, 300))
+
+    # online
+    onlineMvQuality = OptionsConfigItem("Online", "MvQuality", MvQuality.FULL_HD, OptionsValidator(MvQuality), EnumSerializer(MvQuality))
+
+
+# create config object and initialize it
+cfg = Config()
+qconfig.load('config/config.json', cfg)
+```
+
+### Setting card
+
+PyQt-Fluent-Widgets provides many kinds of setting card:
+
+|          Class           | Description                                                  |
+| :----------------------: | ------------------------------------------------------------ |
+|     `HyperlinkCard`      | Setting card with a hyper link                               |
+|    `ColorSettingCard`    | Setting card with a color picker                             |
+| `CustomColorSettingCard` | Setting card with a button to choose color                   |
+|   `ComboBoxSettingCard`  | Setting card with a combo box                                |
+|    `RangeSettingCard`    | Setting card with a slider                                   |
+|    `PushSettingCard`     | Setting card with a naive push button                        |
+| `PrimaryPushSettingCard` | Setting card with a push button highlighted in the background |
+|   `SwitchSettingCard`    | Setting card with a switch button                            |
+|   `OptionsSettingCard`   | Setting card with a group of radio buttons                   |
+| `FolderListSettingCard`  | Setting card for showing and managing folder list            |
+
+You can use `SettingCardGroup.addSettingCard()` to add a setting card to the same group, and `SettingCardGroup` will adjust its layout automatically based on the height of setting cards.
+
+For the usage of these components, see [settings_ interface.py](https://github.com/zhiyiYo/PyQt-Fluent-Widgets/blob/master/examples/settings/setting_interface.py).
+
+

docs/source/theme.md

@@ -0,0 +1,44 @@
+## Theme
+
+### Theme mode
+You can use the `setTheme()` method to switch the light/dark theme of PyQt-Fluent-Widgets. The parameter of `setTheme()` accepts the following three values:
+* `Theme.LIGHT`: Light theme
+* `Theme.DARK`: Dark theme
+* `Theme.AUTO`: Follow system theme. If the system theme cannot be detected, the light theme will be used.
+
+When the theme changes, the config instance managed by `qconfig` (i.e., the config object passed in using the `qconfig.load()` method) will emit the `themeChanged` signal.
+
+If you want to automatically switch the interface style when the theme changes, you can inherit `StyleSheetBase` and override the `path()` method. Suppose you have a `MainWindow` class and its qss file paths are `app/resource/qss/light/main_window.qss` and `app/resource/qss/dark/main_window.qss`, the code can be written like this:
+
+```python
+from enum import Enum
+from qfluentwidgets import StyleSheetBase, Theme, isDarkTheme, qconfig
+
+
+class StyleSheet(StyleSheetBase, Enum):
+    """ Style sheet  """
+
+    MAIN_WINDOW = "main_window"
+
+    def path(self, theme=Theme.AUTO):
+        theme = qconfig.theme if theme == Theme.AUTO else theme
+        return f"app/resource/qss/{theme.value.lower()}/{self.value}.qss"
+
+
+class MainWindow(QWidget):
+
+    def __init__(self, parent=None):
+        super().__init__(parent=parent)
+
+        # apply style sheet to main window
+        StyleSheet.MAIN_WINDOW.apply(self)
+```
+
+
+### Theme color
+You can use `setThemeColor()` method to change the theme color of PyQt-Fluent-Widgets. This method accepts the following three types of parameters:
+* `QColor`
+* `Qt.GlobalColor`
+* `str`: Hex color strings or color names, such as `#0065d5` or `red`.
+
+When the theme color changes, `qconfig` will emit the `themeColorChanged` signal.