diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md new file mode 100644 index 00000000..fb6eb2ac --- /dev/null +++ b/CONTRIBUTING.zh.md @@ -0,0 +1,11 @@ +# 为 PyQtDarkTheme 做出贡献 + +欢迎你，感谢你对 PyQtDarkTheme 的关注和贡献！ + +我们欢迎一切形式的贡献，包括错误报告、错误修复、文档改进、功能增强以及新的想法。 + +## 创建开发环境 + +你可以从阅读以下内容开始： + +- [贡献指南](https://pyqtdarktheme.readthedocs.io/en/latest/contributing.html) \ No newline at end of file diff --git a/README.md b/README.md index 2777aa8b..8f82f081 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@ # PyQtDarkTheme +[简体中文](README.zh.md) + PyQtDarkTheme applies a flat dark theme to QtWidgets application. There's a light theme too. Color balanced from the dark theme for easy viewing in daylight. Check out the [complete documentation](https://pyqtdarktheme.readthedocs.io). **Project status** + [![PyPI Latest Release](https://img.shields.io/pypi/v/pyqtdarktheme.svg?color=orange)](https://pypi.org/project/pyqtdarktheme/) [![Python Versions](https://img.shields.io/pypi/pyversions/pyqtdarktheme.svg?color=blue)](https://www.python.org/downloads/) [![Qt Versions](https://img.shields.io/badge/Qt-5%20|%206-blue.svg?&logo=Qt&logoWidth=18&logoColor=white)](https://www.qt.io/qt-for-python) [![License](https://img.shields.io/github/license/5yutan5/PyQtDarkTheme.svg?color=green)](https://github.com/5yutan5/PyQtDarkTheme/blob/main/LICENSE.txt/) **Tests** + [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/5yutan5/PyQtDarkTheme/main.svg)](https://results.pre-commit.ci/latest/github/5yutan5/PyQtDarkTheme/main) [![codecov](https://codecov.io/gh/5yutan5/PyQtDarkTheme/branch/main/graph/badge.svg?token=RTS8O0V6SF)](https://codecov.io/gh/5yutan5/PyQtDarkTheme) [![Documentation Status](https://readthedocs.org/projects/pyqtdarktheme/badge/?version=latest)](https://pyqtdarktheme.readthedocs.io/en/latest/?badge=latest) diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 00000000..8f0b28d5 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,161 @@ +# PyQtDarkTheme + +PyQtDarkTheme 能够对 QtWidgets 应用程序应用深色主题。也有一个浅色主题。拥有从浅色主题中获得的色彩平衡，方便在日光下查看。 + +请查阅[完整文档中文版](https://pyqtdarkthemecn.readthedocs.io)获取更多信息。 + +**项目状态** + +[![PyPI 最新发布版本](https://img.shields.io/pypi/v/pyqtdarktheme.svg?color=orange)](https://pypi.org/project/pyqtdarktheme/) +[![Python 版本](https://img.shields.io/pypi/pyversions/pyqtdarktheme.svg?color=blue)](https://www.python.org/downloads/) +[![Qt 版本](https://img.shields.io/badge/Qt-5%20|%206-blue.svg?&logo=Qt&logoWidth=18&logoColor=white)](https://www.qt.io/qt-for-python) +[![许可证](https://img.shields.io/github/license/5yutan5/PyQtDarkTheme.svg?color=green)](https://github.com/5yutan5/PyQtDarkTheme/blob/main/LICENSE.txt/) + +**测试** + +[![pre-commit.ci 状态](https://results.pre-commit.ci/badge/github/5yutan5/PyQtDarkTheme/main.svg)](https://results.pre-commit.ci/latest/github/5yutan5/PyQtDarkTheme/main) +[![codecov](https://codecov.io/gh/5yutan5/PyQtDarkTheme/branch/main/graph/badge.svg?token=RTS8O0V6SF)](https://codecov.io/gh/5yutan5/PyQtDarkTheme) +[![文档状态](https://readthedocs.org/projects/pyqtdarktheme/badge/?version=latest)](https://pyqtdarktheme.readthedocs.io/en/latest/?badge=latest) + +## 特性 + +- 简约的深色和浅色主题 +- 支持 PySide 和 PyQt +- 与操作系统的主题同步 (Mac、Windows、Linux) +- 解决不同 Qt 版本之间的风格差异 +- 提供深色/浅色主题的 QPalette +- 覆盖 Qt 旧的标准图标 + +## 主题 + +### 深色主题 + +![深色主题的部件展示](https://raw.githubusercontent.com/5yutan5/PyQtDarkTheme/main/images/widget_gallery_dark.png) + +### 浅色主题 + +![浅色主题的部件展示](https://raw.githubusercontent.com/5yutan5/PyQtDarkTheme/main/images/widget_gallery_light.png) + +## 需求 + +- [Python 3.7+](https://www.python.org/downloads/) +- Qt 5.15+ +- PySide6, PyQt6, PyQt5 或者 PySide2 + +## 安装方法 + +- 最新发布版本 + + ```plaintext + pip install pyqtdarktheme + ``` + +- 最新开发版本 + + ```plaintext + pip install git+https://github.com/5yutan5/PyQtDarkTheme.git@main + ``` + +## 使用方式 + +```Python +import sys + +from PySide6.QtWidgets import QApplication, QMainWindow, QPushButton + +import qdarktheme + +app = QApplication(sys.argv) +# 在你的 Qt 应用上应用完整的暗色主题。 +qdarktheme.setup_theme() + +main_win = QMainWindow() +push_button = QPushButton("PyQtDarkTheme！") +main_win.setCentralWidget(push_button) + +main_win.show() + +app.exec() +``` +更多信息可以在我们的文档中找到： + +- [使用指南](https://pyqtdarktheme.readthedocs.io/en/latest/how_to_use.html) + +### 启用 HiDPI + +```Python +# enable_hi_dpi() 必须在 QApplication 的实例化之前调用。 +qdarktheme.enable_hi_dpi() +app = QApplication(sys.argv) +qdarktheme.setup_theme() +``` + +对于 Qt6 绑定，HiDPI “能够自动工作”而不需要使用此函数。 + +### 浅色主题 + +```Python +qdarktheme.setup_theme("light") +``` + +### 与操作系统的主题和强调色同步 + +```Python +qdarktheme.setup_theme("auto") +``` + +![与操作系统主题同步](https://raw.githubusercontent.com/5yutan5/PyQtDarkTheme/main/images/sync_with_os_theme.gif) + +在macOS上，qdarktheme还可以与强调色同步。 +![与操作系统强调色同步](https://raw.githubusercontent.com/5yutan5/PyQtDarkTheme/main/images/sync_with_os_accent.gif) + +### 定制颜色 + +你可以定制主题颜色。 + +```python +# 定制强调色。 +qdarktheme.setup_theme(custom_colors={"primary": "#D0BCFF"}) +``` + +所有可定制颜色的列表，请见主题颜色参考： + +- [主题颜色](https://pyqtdarktheme.readthedocs.io/en/latest/reference/theme_color.html) + +### 锐利的框边 + +你可以更改角落的样式。 + +```python +# 默认是 "rounded". +stylesheet = qdarktheme.setup_theme(corner_shape="sharp") +``` + +### QPalette 和样式表 + +你也可以只加载 QPalette 和样式表。`qdarktheme.setup_theme` 内部使用以下函数。 + +```Python +palette = qdarktheme.load_palette(theme="dark") +stylesheet = qdarktheme.load_stylesheet(theme="dark") +``` +## 示例 + +要查看所有 Qt 部件，请运行： + +```plaintext +python -m qdarktheme.widget_gallery +``` +## 许可证 + +PyQtDarkTheme 为的 svg 文件源自 [Material design icons](https://fonts.google.com/icons)(Apache License Version 2.0)。Qt 样式表原为 [QDarkStyleSheet](https://github.com/ColinDuquesnoy/QDarkStyleSheet)的分支(MIT License)。其他文件都受到 PyQtDarkTheme 的 MIT 许可证保护。强调色检测器(qdarktheme/_os_appearance/_accent/_mac_detect) 的设计灵感源自[darkdetect](https://github.com/albertosottile/darkdetect)(3-clause BSD License)。 + +## 贡献方式 + +所有的贡献，包括错误报告，错误修复，文档改进，增强、创意等均受到欢迎。你可以从阅读这个开始： + +- [贡献指南](https://pyqtdarktheme.readthedocs.io/en/latest/contributing.html) + +## 变更记录 + +请见[发布记录](https://github.com/5yutan5/PyQtDarkTheme/releases)。 \ No newline at end of file diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index dc83f7f8..19175067 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -1,45 +1,45 @@ -Contributing Guide +贡献指南 ================== -All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. +所有的贡献、错误报告、错误修复、文档改进、增强和想法都是受欢迎的。 -Local development +本地开发 ----------------- -These are the basic steps needed to start developing on PyQtDarkTheme. +以下是开始在 PyQtDarkTheme 上开发所需的基本步骤。 -#. Clone PyQtDarkTheme - You will first need to clone the repository using git and place yourself in its directory: +1. 克隆 PyQtDarkTheme + 首先，你需要使用 git 克隆仓库并进入其目录： .. code-block:: bash $ git@github.com:5yutan5/PyQtDarkTheme.git $ cd PyQtDarkTheme -#. Install Poetry - You will need Poetry to start contributing on the PyQtDarkTheme codebase. Refer to the `Poetry documentation `__ to start using Poetry. -#. Create a virtual environment - Now, you will need to install the required dependency for PyQtDarkTheme with Poetry and install Qt bindings(PySide or PyQt) with pip. +2. 安装 Poetry + 你需要 Poetry 来开始在 PyQtDarkTheme 代码库上贡献。参考 `Poetry 文档 `__ 来开始使用 Poetry。 +3. 创建虚拟环境 + 现在，你需要用 Poetry 安装 PyQtDarkTheme 所需的依赖，并用 pip 安装 Qt 绑定（PySide 或 PyQt）。 .. code-block:: bash $ poetry install $ poetry run pip install PySide6 -#. Run Pytest - You need to be sure that the current tests are passing on your machine: +4. 运行 Pytest + 你需要确保当前的测试在你的机器上通过： .. code-block:: bash $ poetry run pytest tests -#. Setup pre-commit - To make sure that you don't accidentally commit code that does not follow the coding style, you can install a pre-commit hook that will check that everything is in order: +5. 设置 pre-commit + 为了确保你不会意外地提交不符合编码风格的代码，你可以安装一个 pre-commit 钩子，它会检查一切是否正常： .. code-block:: bash $ poetry run pre-commit install -#. Check Qt theme - You can check dark/light theme with built-in app. +6. 检查 Qt 主题 + 你可以使用内置应用检查深色/浅色主题。 .. code-block:: bash - $ poetry run python -m qdarktheme.widget_gallery + $ poetry run python -m qdarktheme.widget_gallery \ No newline at end of file diff --git a/docs/source/how_to_use.rst b/docs/source/how_to_use.rst index 628e2e5f..00bd932b 100644 --- a/docs/source/how_to_use.rst +++ b/docs/source/how_to_use.rst @@ -1,10 +1,10 @@ -How to use PyQtDarkTheme +如何使用 PyQtDarkTheme ======================== -Apply dark theme to your Qt Application +将深色主题应用于您的 Qt 应用程序 --------------------------------------- -PyQtDarkTheme applies a flat theme to your Qt applications. +PyQtDarkTheme 为您的 Qt 应用程序提供了一个扁平主题。 .. tab-set:: @@ -28,39 +28,39 @@ PyQtDarkTheme applies a flat theme to your Qt applications. .. literalinclude:: ../../examples/apply_theme/pyqtgraph.py -Enable HiDPI +启用 HiDPI ------------ -If you want to enable HiDPI, you can use ``qdarktheme.enable_hi_dpi()``. For Qt6 bindings, HiDPI “just works” without using this function. +如果您想启用 HiDPI，可以使用 ``qdarktheme.enable_hi_dpi()``。对于 Qt6 绑定，无需使用此函数，HiDPI 就可以正常工作。 .. code-block:: python - # enable_hi_dpi() must be called before instantiation of QApplication. + # 必须在 QApplication 实例化之前调用 enable_hi_dpi()。 qdarktheme.enable_hi_dpi() app = QApplication(sys.argv) -Toggle dark/light Theme +切换深/浅主题 ----------------------- -If you add ``theme`` argument as "auto", your Qt Application sync with OS's theme. On macOS, qdarktheme also syncs with accent colors. +如果您将 ``theme`` 参数设置为 "auto"，您的 Qt 应用程序将与操作系统的主题同步。在 macOS 上，qdarktheme 也会与突出颜色同步。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: python qdarktheme.setup_theme("auto") - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/toggle_theme/sync_with_os_theme.py -You can also switch between light and dark theme manually. +您还可以手动切换深色和浅色主题。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: python @@ -68,18 +68,18 @@ You can also switch between light and dark theme manually. combo_box.addItems(qdarktheme.get_themes()) combo_box.currentTextChanged.connect(qdarktheme.setup_theme) - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/toggle_theme/toggle_dark_light.py -Toggle dark/light Theme with pyqtgraph +使用 pyqtgraph 切换深/浅主题 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can also switch between light and dark theme with pyqtgraph. +您也可以使用 pyqtgraph 切换深色和浅色主题。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: python @@ -90,58 +90,58 @@ You can also switch between light and dark theme with pyqtgraph. signal.connect(toggle_theme) - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/toggle_theme/toggle_with_pyqtgraph.py -Theme customization +主题定制 ------------------- -You can customize theme color. +您可以定制主题颜色。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: python qdarktheme.setup_theme(custom_colors={"primary": "#D0BCFF"}) - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/customize_color/customize_accent_color.py - .. tab-item:: Result + .. tab-item:: 结果 .. image:: ../../examples/customize_color/customize_accent_color.png :class: dark-light -You can also change border corner shape. +您还可以更改边框圆角形状。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: Python qdarktheme.setup_theme(corner_shape="sharp") - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/customize_style/change_corner_to_sharp.py - .. tab-item:: Result + .. tab-item:: 结果 .. image:: ../../examples/customize_style/change_corner_to_sharp.png :class: dark-light -Append your own stylesheets +附加您自己的样式表 --------------------------- .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: Python @@ -153,23 +153,23 @@ Append your own stylesheets """ qdarktheme.setup_theme(additional_qss=qss) - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/customize_style/append_stylesheet.py - .. tab-item:: Result + .. tab-item:: 结果 .. image:: ../../examples/customize_style/append_stylesheet.png :class: dark-light -Use overridden Qt default icons +使用覆盖的 Qt 默认图标 ------------------------------- -If you setup theme with ``qdarktheme.setup_theme``, qdarktheme override ``QStyle.standardIcon()``. So you can easily use some `Google Material Design Icons `_. And these icons change color that adjust to theme when theme is changed. +如果您使用 ``qdarktheme.setup_theme`` 设置主题，qdarktheme 将覆盖 ``QStyle.standardIcon()``。因此，您可以轻松使用一些 `Google Material Design Icons `_。当主题更改时，这些图标颜色会自动调整以适应主题。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: Python @@ -179,42 +179,42 @@ If you setup theme with ``qdarktheme.setup_theme``, qdarktheme override ``QStyle push_button = QPushButton("Save") push_button.setIcon(save_icon) - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/icons/use_standard_icons.py - .. tab-item:: Result + .. tab-item:: 结果 .. image:: ../../examples/icons/use_standard_icons.png - .. tab-item:: Gallery + .. tab-item:: 图库 .. image:: ../../images/standard_icons.png -Use QPalette to your Qt Application +将 QPalette 应用于您的 Qt 应用程序 ----------------------------------- -You can apply dark and light color to your Qt Application using QPalette of PyQtDarkTheme. +您可以使用 PyQtDarkTheme 的 QPalette 为您的 Qt 应用程序应用深色和浅色的颜色。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: Python qdarktheme.load_palette() - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/qpalette/apply_dark_palette.py - .. tab-item:: Gallery + .. tab-item:: 图库 .. image:: ../../images/widget_gallery_dark_qpalette.png :class: dark-light -And you can get theme color from QPalette of PyQtDarkTheme. +您还可以从 PyQtDarkTheme 的 QPalette 中获取主题颜色。 .. code-block:: Python @@ -224,19 +224,19 @@ And you can get theme color from QPalette of PyQtDarkTheme. link_color = dark_palette.link().color() link_rgb = link_color.getRgb() -Use stylesheet +使用样式表 -------------- -If you want to use Qt stylesheet of PyQtDarkTheme, use following function. +如果您想使用 PyQtDarkTheme 的 Qt 样式表，请使用以下函数。 .. tab-set:: - .. tab-item:: Source + .. tab-item:: 源码 .. code-block:: Python qdarktheme.load_stylesheet() - .. tab-item:: Full source + .. tab-item:: 完整源码 .. literalinclude:: ../../examples/use_stylesheet/apply_stylesheet.py diff --git a/docs/source/index.rst b/docs/source/index.rst index a9a67a1d..4670ca63 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,41 +1,41 @@ -PyQtDarkTheme documentation +PyQtDarkTheme 文档 =========================== -PyQtDarkTheme applies a flat dark theme to QtWidgets application(PySide and PyQt). There's a light theme too. Color and style balanced from a dark theme for easy viewing in daylight. +PyQtDarkTheme 提供了一个扁平化的深色主题给 QtWidgets 应用程序(PySide 和 PyQt)。也有一个浅色主题。颜色和样式是从深色主题中平衡选择的，以便在日光下易于查看。 .. tab-set:: - .. tab-item:: Dark + .. tab-item:: 深色 .. image:: ../../images/widget_gallery_dark.png :class: dark-light - .. tab-item:: Light + .. tab-item:: 浅色 .. image:: ../../images/widget_gallery_light.png :class: dark-light - .. tab-item:: Sync with OS's theme + .. tab-item:: 与操作系统主题同步 .. image:: ../../images/sync_with_os_theme.gif :class: dark-light -**Features:** +**特性:** -* A flat dark/light theme -* Support PySide, PyQt and PyInstaller -* Sync with OS's theme and accent (Mac, Windows, Linux) -* Resolve the style differences between Qt versions -* Provide dark/light theme QPalette -* :ref:`Override Qt old standard icons `. +* 扁平化的深色/浅色主题 +* 支持 PySide, PyQt 和 PyInstaller +* 与操作系统的主题和色调同步（Mac, Windows, Linux） +* 解决 Qt 版本之间的样式差异 +* 提供深色/浅色主题的 QPalette +* :ref:`覆盖 Qt 旧版标准图标 `。 ++++ .. grid:: :gutter: 2 - .. grid-item-card:: Installation guide + .. grid-item-card:: 安装指南 :text-align: center :link: installation_guide :link-type: doc @@ -44,7 +44,7 @@ PyQtDarkTheme applies a flat dark theme to QtWidgets application(PySide and PyQt :material-regular:`install_desktop;5em;sd-text-primary` ^^^ - .. grid-item-card:: How to use + .. grid-item-card:: 如何使用 :text-align: center :link: how_to_use :link-type: doc @@ -53,7 +53,7 @@ PyQtDarkTheme applies a flat dark theme to QtWidgets application(PySide and PyQt :material-regular:`menu_book;5em;sd-text-primary` ^^^ - .. grid-item-card:: API reference + .. grid-item-card:: API 参考 :text-align: center :link: reference/index :link-type: doc @@ -62,7 +62,7 @@ PyQtDarkTheme applies a flat dark theme to QtWidgets application(PySide and PyQt :material-regular:`library_books;5em;sd-text-primary` ^^^ - .. grid-item-card:: Contributing + .. grid-item-card:: 贡献 :text-align: center :link: contributing :link-type: doc @@ -75,7 +75,7 @@ PyQtDarkTheme applies a flat dark theme to QtWidgets application(PySide and PyQt :maxdepth: 2 :hidden: - Installation guide - How to use - API reference - Contributing + 安装指南 + 如何使用 + API 参考 + 贡献 \ No newline at end of file diff --git a/docs/source/installation_guide.rst b/docs/source/installation_guide.rst index d65b9041..40073d86 100644 --- a/docs/source/installation_guide.rst +++ b/docs/source/installation_guide.rst @@ -1,33 +1,33 @@ -Installation Guide +安装指南 ================== -Dependencies +依赖 ------------ * Python 3.7+ * Qt 5.15+ -* PySide6, PyQt6, PyQt5 or PySide2 +* PySide6、PyQt6、PyQt5 或 PySide2 -Installation +安装 ------------ .. tab-set:: .. tab-item:: PyPi - PyQtDarkTheme can be installed via pip from `PyPI `__. :: + PyQtDarkTheme 可以通过 pip 从 `PyPI `__ 安装。:: pip install pyqtdarktheme .. tab-item:: GitHub - To get access to the latest features and bugfixes you can install PyQtDarkTheme from GitHub. :: + 为了获取最新功能和错误修复，你可以从 GitHub 安装 PyQtDarkTheme。:: pip install git+https://github.com/5yutan5/PyQtDarkTheme.git@main -Example App +示例应用 ----------- -PyQtDarkTheme includes example app that can be accessed by running: :: +PyQtDarkTheme 包含了可以通过以下命令访问的示例应用程序：:: - python -m qdarktheme.widget_gallery + python -m qdarktheme.widget_gallery \ No newline at end of file diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index ccca3d3a..008504ad 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -1,10 +1,10 @@ -API Reference +API 参考 ============= -This page gives an overview of all public qdarktheme objects, functions and theme color. All functions exposed in ``qdarktheme.*`` namespace are public. +此页面提供了所有公开的 qdarktheme 对象、函数及主题颜色的概览。在 ``qdarktheme.*`` 命名空间中公开的所有函数都是公开的。 .. toctree:: :maxdepth: 2 qdarktheme - Theme Color + 主题颜色 diff --git a/docs/source/reference/qdarktheme.rst b/docs/source/reference/qdarktheme.rst index ba761a67..e857ae1d 100644 --- a/docs/source/reference/qdarktheme.rst +++ b/docs/source/reference/qdarktheme.rst @@ -1,7 +1,7 @@ qdarktheme ========== -``qdarktheme`` is a python module to apply original theme to PySide and PyQt. +``qdarktheme`` 是一个 Python 模块，用于将原始主题应用于 PySide 和 PyQt。 .. currentmodule:: qdarktheme @@ -17,4 +17,4 @@ qdarktheme .. autofunction:: qdarktheme.get_themes -.. autofunction:: qdarktheme.clear_cache +.. autofunction:: qdarktheme.clear_cache \ No newline at end of file