# 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
* Supports positioning relative to widgets
* 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 whether the toasts should always be shown on the main screen (<u>static</u>):**
```python
Toast.setAlwaysOnMainScreen(True) # Default: False
```
* **Positioning the toasts relative to a widget instead of a screen (<u>static</u>):**
```python
Toast.setPositionRelativeToWidget(some_widget) # Default: None
```
* **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
```
* **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) # Default: False
# Or setting a custom icon:
toast.setIcon(QPixmap('path/to/your/icon.png'))
# If you want to show the icon without recoloring it, set the icon color to None:
toast.setIconColor(None) # Default: #5C5C5C
```
> **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('Times', 10, QFont.Weight.Bold)
# Set fonts
toast.setTitleFont(font) # Default: QFont('Arial', 9, QFont.Weight.Bold)
toast.setTextFont(font) # Default: QFont('Arial', 9)
```
* **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` |
| `setMovePositionWithWidget()` | Whether the toasts should move with widget if positioned relative to a widget | `True` |
| `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/34/21/7cebe3688ea651aef4f459b8080288ba3de68d2d6f6a6f9447bafa3af34b/pyqt-toast-notification-1.3.2.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* Supports positioning relative to widgets\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 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* **Positioning the toasts relative to a widget instead of a screen (<u>static</u>):**\r\n```python\r\nToast.setPositionRelativeToWidget(some_widget) # Default: None\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* **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) # Default: False\r\n\r\n# Or setting a custom icon:\r\ntoast.setIcon(QPixmap('path/to/your/icon.png'))\r\n\r\n# If you want to show the icon without recoloring it, set the icon color to None:\r\ntoast.setIconColor(None) # Default: #5C5C5C\r\n```\r\n> **AVAILABLE ICONS:** <br> `SUCCESS`, `WARNING`, `ERROR`, `INFORMATION`, `CLOSE`\r\n\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('Times', 10, QFont.Weight.Bold)\r\n\r\n# Set fonts\r\ntoast.setTitleFont(font) # Default: QFont('Arial', 9, QFont.Weight.Bold)\r\ntoast.setTextFont(font) # Default: QFont('Arial', 9)\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| `setMovePositionWithWidget()` | Whether the toasts should move with widget if positioned relative to a widget | `True` |\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.3.2",
"project_urls": {
"Homepage": "https://github.com/niklashenning/pyqttoast"
},
"split_keywords": [
"python",
" pyqt",
" qt",
" toast",
" notification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cccd1b110fcccff12928e39d894164bf6e6af59559ac679a8df18c03cfbdd802",
"md5": "4c821ece7a0b7d52645ac769a2ebb699",
"sha256": "82688101202737736d51ab6c74a573b32266ecb7c8b0002f913407bd369737d9"
},
"downloads": -1,
"filename": "pyqt_toast_notification-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c821ece7a0b7d52645ac769a2ebb699",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 40742,
"upload_time": "2024-08-27T14:25:41",
"upload_time_iso_8601": "2024-08-27T14:25:41.492954Z",
"url": "https://files.pythonhosted.org/packages/cc/cd/1b110fcccff12928e39d894164bf6e6af59559ac679a8df18c03cfbdd802/pyqt_toast_notification-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34217cebe3688ea651aef4f459b8080288ba3de68d2d6f6a6f9447bafa3af34b",
"md5": "3735b58ac4ba9f1db9b1ad7df524c40c",
"sha256": "135736ec0f16bff41104dee3c60ac318e5d55ae3378bf26892c6d08c36088ae6"
},
"downloads": -1,
"filename": "pyqt-toast-notification-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "3735b58ac4ba9f1db9b1ad7df524c40c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 40020,
"upload_time": "2024-08-27T14:25:42",
"upload_time_iso_8601": "2024-08-27T14:25:42.992594Z",
"url": "https://files.pythonhosted.org/packages/34/21/7cebe3688ea651aef4f459b8080288ba3de68d2d6f6a6f9447bafa3af34b/pyqt-toast-notification-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-27 14:25:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "niklashenning",
"github_project": "pyqttoast",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"requirements": [
{
"name": "QtPy",
"specs": [
[
">=",
"2.4.1"
]
]
}
],
"lcname": "pyqt-toast-notification"
}
JSON
