# PyQt Toast
[](https://pypi.org/project/pyqt-toast-notification/)
[](https://github.com/niklashenning/pyqttoast)
[](https://github.com/niklashenning/pyqttoast)
[](https://github.com/niklashenning/pyqttoast)
[](https://github.com/niklashenning/pyqttoast/blob/master/LICENSE)
A fully customizable and modern toast notification library for PyQt and PySide
## Features
* Supports showing multiple toasts at the same time
* Supports queueing of toasts
* Supports 7 different positions
* Supports multiple screens
* Modern and fully customizable UI
* Works with `PyQt5`, `PyQt6`, `PySide2`, and `PySide6`
## Installation
```
pip install pyqt-toast-notification
```
## Usage
Import the `Toast` class, instantiate it, and show the toast notification with the `show()` method:
```python
from PyQt6.QtWidgets import QMainWindow, QPushButton
from pyqttoast import Toast, ToastPreset
class Window(QMainWindow):
def __init__(self):
super().__init__(parent=None)
# Add button and connect click event
self.button = QPushButton(self)
self.button.setText('Show toast')
self.button.clicked.connect(self.show_toast)
# Shows a toast notification every time the button is clicked
def show_toast(self):
toast = Toast(self)
toast.setDuration(5000) # Hide after 5 seconds
toast.setTitle('Success! Confirmation email sent.')
toast.setText('Check your email to complete signup.')
toast.applyPreset(ToastPreset.SUCCESS) # Apply style preset
toast.show()
```
> **IMPORTANT:** <br>An instance of `Toast` can only be shown **once**. If you want to show another one, even if the content is exactly the same, you have to create another instance.
## Customization
* **Setting the position of the toasts (<u>static</u>):**
```python
Toast.setPosition(ToastPosition.BOTTOM_MIDDLE) # Default: ToastPosition.BOTTOM_RIGHT
```
> **AVAILABLE POSITIONS:** <br> `BOTTOM_LEFT`, `BOTTOM_MIDDLE`, `BOTTOM_RIGHT`, `TOP_LEFT`, `TOP_MIDDLE`, `TOP_RIGHT`, `CENTER`
* **Setting a limit on how many toasts can be shown at the same time (<u>static</u>):**
```python
Toast.setMaximumOnScreen(5) # Default: 3
```
> If you try to show more toasts than the maximum amount on screen, they will get added to a queue and get shown as soon as one of the currently showing toasts is closed.
* **Setting the vertical spacing between the toasts (<u>static</u>):**
```python
Toast.setSpacing(20) # Default: 10
```
* **Setting the x and y offset of the toast position (<u>static</u>):**
```python
Toast.setOffset(30, 55) # Default: 20, 45
```
* **Setting whether the toasts should always be shown on the main screen (<u>static</u>):**
```python
Toast.setAlwaysOnMainScreen(True) # Default: False
```
* **Making the toast show forever until it is closed:**
```python
toast.setDuration(0) # Default: 5000
```
* **Enabling or disabling the duration bar:**
```python
toast.setShowDurationBar(False) # Default: True
```
* **Adding an icon:**
```python
toast.setIcon(ToastIcon.SUCCESS) # Default: ToastIcon.INFORMATION
toast.setShowIcon(True)
# Or setting a custom icon:
toast.setIcon(QPixmap('path/to/your/icon.png'))
```
> **AVAILABLE ICONS:** <br> `SUCCESS`, `WARNING`, `ERROR`, `INFORMATION`, `CLOSE`
* **Setting the icon size:**
```python
toast.setIconSize(QSize(14, 14)) # Default: QSize(18, 18)
```
* **Enabling or disabling the icon separator:**
```python
toast.setShowIconSeparator(False) # Default: True
```
* **Setting the close button alignment:**
```python
toast.setCloseButtonAlignment(ToastButtonAlignment.MIDDLE) # Default: ToastButtonAlignment.TOP
```
> **AVAILABLE ALIGNMENTS:** <br> `TOP`, `MIDDLE`, `BOTTOM`
* **Enabling or disabling the close button:**
```python
toast.setShowCloseButton(False) # Default: True
```
* **Customizing the duration of the fade animations (milliseconds):**
```python
toast.setFadeInDuration(100) # Default: 250
toast.setFadeOutDuration(150) # Default: 250
```
* **Enabling or disabling duration reset on hover:**
```python
toast.setResetDurationOnHover(False) # Default: True
```
* **Making the corners rounded:**
```python
toast.setBorderRadius(3) # Default: 0
```
* **Setting custom colors:**
```python
toast.setBackgroundColor(QColor('#292929')) # Default: #E7F4F9
toast.setTitleColor(QColor('#FFFFFF')) # Default: #000000
toast.setTextColor(QColor('#D0D0D0')) # Default: #5C5C5C
toast.setDurationBarColor(QColor('#3E9141')) # Default: #5C5C5C
toast.setIconColor(QColor('#3E9141')) # Default: #5C5C5C
toast.setIconSeparatorColor(QColor('#585858')) # Default: #D9D9D9
toast.setCloseButtonIconColor(QColor('#C9C9C9')) # Default: #000000
```
* **Setting custom fonts:**
```python
# Init font
font = QFont()
font.setFamily('Times')
font.setPointSize(10)
font.setBold(True)
# Set fonts
toast.setTitleFont(font)
toast.setTextFont(font)
```
* **Applying a style preset:**
```python
toast.applyPreset(ToastPreset.ERROR)
```
> **AVAILABLE PRESETS:** <br> `SUCCESS`, `WARNING`, `ERROR`, `INFORMATION`, `SUCCESS_DARK`, `WARNING_DARK`, `ERROR_DARK`, `INFORMATION_DARK`
* **Setting toast size constraints:**
```python
# Minimum and maximum size
toast.setMinimumWidth(100)
toast.setMaximumWidth(350)
toast.setMinimumHeight(50)
toast.setMaximumHeight(120)
# Fixed size (not recommended)
toast.setFixedSize(QSize(350, 80))
```
**<br>Other customization options:**
| Option | Description | Default |
|----------------------------|---------------------------------------------------------------------------------|----------------------------|
| `setFixedScreen()` | Fixed screen where the toasts will be shown (static) | `None` |
| `setIconSeparatorWidth()` | Width of the icon separator that separates the icon and text section | `2` |
| `setCloseButtonIcon()` | Icon of the close button | `ToastIcon.CLOSE` |
| `setCloseButtonIconSize()` | Size of the close button icon | `QSize(10, 10)` |
| `setCloseButtonSize()` | Size of the close button | `QSize(24, 24)` |
| `setStayOnTop()` | Whether the toast stays on top of other windows even when they are focused | `True` |
| `setTextSectionSpacing()` | Vertical spacing between the title and the text | `8` |
| `setMargins()` | Margins around the whole toast content | `QMargins(20, 18, 10, 18)` |
| `setIconMargins()` | Margins around the icon | `QMargins(0, 0, 15, 0)` |
| `setIconSectionMargins()` | Margins around the icon section (the area with the icon and the icon separator) | `QMargins(0, 0, 15, 0)` |
| `setTextSectionMargins()` | Margins around the text section (the area with the title and the text) | `QMargins(0, 0, 15, 0)` |
| `setCloseButtonMargins()` | Margins around the close button | `QMargins(0, -8, 0, -8)` |
## Demo
https://github.com/niklashenning/pyqt-toast/assets/58544929/f4d7f4a4-6d69-4087-ae19-da54b6da499d
The demos for PyQt5, PyQt6, and PySide6 can be found in the [demo](demo) folder.
## Tests
Installing the required test dependencies [PyQt6](https://pypi.org/project/PyQt6/), [pytest](https://github.com/pytest-dev/pytest), and [coveragepy](https://github.com/nedbat/coveragepy):
```
pip install PyQt6 pytest coverage
```
To run the tests with coverage, clone this repository, go into the main directory and run:
```
coverage run -m pytest
coverage report --ignore-errors -m
```
## License
This software is licensed under the [MIT license](https://github.com/niklashenning/pyqttoast/blob/master/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/niklashenning/pyqttoast",
"name": "pyqt-toast-notification",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "python, pyqt, qt, toast, notification",
"author": "Niklas Henning",
"author_email": "business@niklashenning.com",
"download_url": "https://files.pythonhosted.org/packages/e6/8b/1dd2ef68b1e614749387ce82164e9aae89ac42b5adf656dfe22115a54a71/pyqt-toast-notification-1.2.0.tar.gz",
"platform": null,
"description": "\r\n# PyQt Toast\r\n\r\n[](https://pypi.org/project/pyqt-toast-notification/)\r\n[](https://github.com/niklashenning/pyqttoast)\r\n[](https://github.com/niklashenning/pyqttoast)\r\n[](https://github.com/niklashenning/pyqttoast)\r\n[](https://github.com/niklashenning/pyqttoast/blob/master/LICENSE)\r\n\r\nA fully customizable and modern toast notification library for PyQt and PySide\r\n\r\n\r\n\r\n## Features\r\n* Supports showing multiple toasts at the same time\r\n* Supports queueing of toasts\r\n* Supports 7 different positions\r\n* Supports multiple screens\r\n* Modern and fully customizable UI\r\n* Works with `PyQt5`, `PyQt6`, `PySide2`, and `PySide6`\r\n\r\n## Installation\r\n```\r\npip install pyqt-toast-notification\r\n```\r\n\r\n## Usage\r\nImport the `Toast` class, instantiate it, and show the toast notification with the `show()` method:\r\n\r\n```python\r\nfrom PyQt6.QtWidgets import QMainWindow, QPushButton\r\nfrom pyqttoast import Toast, ToastPreset\r\n\r\n\r\nclass Window(QMainWindow):\r\n def __init__(self):\r\n super().__init__(parent=None)\r\n\r\n # Add button and connect click event\r\n self.button = QPushButton(self)\r\n self.button.setText('Show toast')\r\n self.button.clicked.connect(self.show_toast)\r\n \r\n # Shows a toast notification every time the button is clicked\r\n def show_toast(self):\r\n toast = Toast(self)\r\n toast.setDuration(5000) # Hide after 5 seconds\r\n toast.setTitle('Success! Confirmation email sent.')\r\n toast.setText('Check your email to complete signup.')\r\n toast.applyPreset(ToastPreset.SUCCESS) # Apply style preset\r\n toast.show()\r\n```\r\n\r\n> **IMPORTANT:** <br>An instance of `Toast` can only be shown **once**. If you want to show another one, even if the content is exactly the same, you have to create another instance.\r\n\r\n\r\n## Customization\r\n\r\n* **Setting the position of the toasts (<u>static</u>):**\r\n```python\r\nToast.setPosition(ToastPosition.BOTTOM_MIDDLE) # Default: ToastPosition.BOTTOM_RIGHT\r\n```\r\n> **AVAILABLE POSITIONS:** <br> `BOTTOM_LEFT`, `BOTTOM_MIDDLE`, `BOTTOM_RIGHT`, `TOP_LEFT`, `TOP_MIDDLE`, `TOP_RIGHT`, `CENTER`\r\n\r\n\r\n* **Setting a limit on how many toasts can be shown at the same time (<u>static</u>):**\r\n```python\r\nToast.setMaximumOnScreen(5) # Default: 3\r\n```\r\n> If you try to show more toasts than the maximum amount on screen, they will get added to a queue and get shown as soon as one of the currently showing toasts is closed.\r\n\r\n\r\n* **Setting the vertical spacing between the toasts (<u>static</u>):**\r\n```python\r\nToast.setSpacing(20) # Default: 10\r\n```\r\n\r\n* **Setting the x and y offset of the toast position (<u>static</u>):**\r\n```python\r\nToast.setOffset(30, 55) # Default: 20, 45\r\n```\r\n\r\n* **Setting whether the toasts should always be shown on the main screen (<u>static</u>):**\r\n```python\r\nToast.setAlwaysOnMainScreen(True) # Default: False\r\n```\r\n\r\n* **Making the toast show forever until it is closed:**\r\n```python\r\ntoast.setDuration(0) # Default: 5000\r\n```\r\n\r\n* **Enabling or disabling the duration bar:**\r\n```python\r\ntoast.setShowDurationBar(False) # Default: True\r\n```\r\n\r\n* **Adding an icon:**\r\n```python\r\ntoast.setIcon(ToastIcon.SUCCESS) # Default: ToastIcon.INFORMATION\r\ntoast.setShowIcon(True)\r\n\r\n# Or setting a custom icon:\r\ntoast.setIcon(QPixmap('path/to/your/icon.png'))\r\n```\r\n> **AVAILABLE ICONS:** <br> `SUCCESS`, `WARNING`, `ERROR`, `INFORMATION`, `CLOSE`\r\n\r\n* **Setting the icon size:**\r\n```python\r\ntoast.setIconSize(QSize(14, 14)) # Default: QSize(18, 18)\r\n```\r\n\r\n* **Enabling or disabling the icon separator:**\r\n```python\r\ntoast.setShowIconSeparator(False) # Default: True\r\n```\r\n\r\n* **Setting the close button alignment:**\r\n```python\r\ntoast.setCloseButtonAlignment(ToastButtonAlignment.MIDDLE) # Default: ToastButtonAlignment.TOP\r\n```\r\n> **AVAILABLE ALIGNMENTS:** <br> `TOP`, `MIDDLE`, `BOTTOM`\r\n\r\n* **Enabling or disabling the close button:**\r\n```python\r\ntoast.setShowCloseButton(False) # Default: True\r\n```\r\n\r\n* **Customizing the duration of the fade animations (milliseconds):**\r\n```python\r\ntoast.setFadeInDuration(100) # Default: 250\r\ntoast.setFadeOutDuration(150) # Default: 250\r\n```\r\n\r\n* **Enabling or disabling duration reset on hover:**\r\n\r\n```python\r\ntoast.setResetDurationOnHover(False) # Default: True\r\n```\r\n\r\n* **Making the corners rounded:**\r\n```python\r\ntoast.setBorderRadius(3) # Default: 0\r\n```\r\n\r\n* **Setting custom colors:**\r\n```python\r\ntoast.setBackgroundColor(QColor('#292929')) # Default: #E7F4F9\r\ntoast.setTitleColor(QColor('#FFFFFF')) # Default: #000000\r\ntoast.setTextColor(QColor('#D0D0D0')) # Default: #5C5C5C\r\ntoast.setDurationBarColor(QColor('#3E9141')) # Default: #5C5C5C\r\ntoast.setIconColor(QColor('#3E9141')) # Default: #5C5C5C\r\ntoast.setIconSeparatorColor(QColor('#585858')) # Default: #D9D9D9\r\ntoast.setCloseButtonIconColor(QColor('#C9C9C9')) # Default: #000000\r\n```\r\n\r\n* **Setting custom fonts:**\r\n```python\r\n# Init font\r\nfont = QFont()\r\nfont.setFamily('Times')\r\nfont.setPointSize(10)\r\nfont.setBold(True)\r\n\r\n# Set fonts\r\ntoast.setTitleFont(font)\r\ntoast.setTextFont(font)\r\n```\r\n\r\n* **Applying a style preset:**\r\n```python\r\ntoast.applyPreset(ToastPreset.ERROR)\r\n```\r\n> **AVAILABLE PRESETS:** <br> `SUCCESS`, `WARNING`, `ERROR`, `INFORMATION`, `SUCCESS_DARK`, `WARNING_DARK`, `ERROR_DARK`, `INFORMATION_DARK`\r\n\r\n* **Setting toast size constraints:**\r\n```python\r\n# Minimum and maximum size\r\ntoast.setMinimumWidth(100)\r\ntoast.setMaximumWidth(350)\r\ntoast.setMinimumHeight(50)\r\ntoast.setMaximumHeight(120)\r\n\r\n# Fixed size (not recommended)\r\ntoast.setFixedSize(QSize(350, 80))\r\n```\r\n\r\n\r\n**<br>Other customization options:**\r\n\r\n| Option | Description | Default |\r\n|----------------------------|---------------------------------------------------------------------------------|----------------------------|\r\n| `setFixedScreen()` | Fixed screen where the toasts will be shown (static) | `None` |\r\n| `setIconSeparatorWidth()` | Width of the icon separator that separates the icon and text section | `2` |\r\n| `setCloseButtonIcon()` | Icon of the close button | `ToastIcon.CLOSE` |\r\n| `setCloseButtonIconSize()` | Size of the close button icon | `QSize(10, 10)` |\r\n| `setCloseButtonSize()` | Size of the close button | `QSize(24, 24)` |\r\n| `setStayOnTop()` | Whether the toast stays on top of other windows even when they are focused | `True` |\r\n| `setTextSectionSpacing()` | Vertical spacing between the title and the text | `8` |\r\n| `setMargins()` | Margins around the whole toast content | `QMargins(20, 18, 10, 18)` |\r\n| `setIconMargins()` | Margins around the icon | `QMargins(0, 0, 15, 0)` |\r\n| `setIconSectionMargins()` | Margins around the icon section (the area with the icon and the icon separator) | `QMargins(0, 0, 15, 0)` |\r\n| `setTextSectionMargins()` | Margins around the text section (the area with the title and the text) | `QMargins(0, 0, 15, 0)` |\r\n| `setCloseButtonMargins()` | Margins around the close button | `QMargins(0, -8, 0, -8)` |\r\n\r\n## Demo\r\nhttps://github.com/niklashenning/pyqt-toast/assets/58544929/f4d7f4a4-6d69-4087-ae19-da54b6da499d\r\n\r\nThe demos for PyQt5, PyQt6, and PySide6 can be found in the [demo](demo) folder.\r\n\r\n## Tests\r\nInstalling the required test dependencies [PyQt6](https://pypi.org/project/PyQt6/), [pytest](https://github.com/pytest-dev/pytest), and [coveragepy](https://github.com/nedbat/coveragepy):\r\n```\r\npip install PyQt6 pytest coverage\r\n```\r\n\r\nTo run the tests with coverage, clone this repository, go into the main directory and run:\r\n```\r\ncoverage run -m pytest\r\ncoverage report --ignore-errors -m\r\n```\r\n\r\n## License\r\nThis software is licensed under the [MIT license](https://github.com/niklashenning/pyqttoast/blob/master/LICENSE).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fully customizable toast notification library for PyQt and PySide",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/niklashenning/pyqttoast"
},
"split_keywords": [
"python",
" pyqt",
" qt",
" toast",
" notification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e5c2351b1046a337b39a13f70bdc29f34856e9ea5fcdcea151c7d74a3639c8d3",
"md5": "7753f2bbc6880b94d27c7744facba88a",
"sha256": "450c377e39cce4ef73bf869bcfdaaab0c1180892802b4951b80bdbd06169e9cf"
},
"downloads": -1,
"filename": "pyqt_toast_notification-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7753f2bbc6880b94d27c7744facba88a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 37520,
"upload_time": "2024-05-13T07:30:02",
"upload_time_iso_8601": "2024-05-13T07:30:02.632452Z",
"url": "https://files.pythonhosted.org/packages/e5/c2/351b1046a337b39a13f70bdc29f34856e9ea5fcdcea151c7d74a3639c8d3/pyqt_toast_notification-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e68b1dd2ef68b1e614749387ce82164e9aae89ac42b5adf656dfe22115a54a71",
"md5": "a7497947c9ea410b5ebd10292d12c58c",
"sha256": "9a401de25cd9256e3caa1f5467a9c66e6e0ea1c6268995d19e04b8feecaec85b"
},
"downloads": -1,
"filename": "pyqt-toast-notification-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a7497947c9ea410b5ebd10292d12c58c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 37859,
"upload_time": "2024-05-13T07:30:04",
"upload_time_iso_8601": "2024-05-13T07:30:04.696266Z",
"url": "https://files.pythonhosted.org/packages/e6/8b/1dd2ef68b1e614749387ce82164e9aae89ac42b5adf656dfe22115a54a71/pyqt-toast-notification-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 07:30:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "niklashenning",
"github_project": "pyqttoast",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"requirements": [],
"lcname": "pyqt-toast-notification"
}
JSON
