# FrostedGlass
**FrostedGlass** is a widget with translucent frosted glass effect, that
creates a context with the background behind it.
The effect created is based on the widget/layout passed in as the background.
You can control the blur size, saturation, luminosity, overlay color, noise
opacity, border radius and the outline (color and width).
[](https://github.com/kivy-garden/frostedglass/actions)
[](https://pypi.org/project/kivy-garden.frostedglass/)
## Install
pip install kivy_garden.frostedglass
## Import
**_python_ import:**
from kivy_garden.frostedglass import FrostedGlass
**or _kvlang_ import:**
#: import FrostedGlass kivy_garden.frostedglass
## Usage
*FrostedGlass* will apply the effect to the background passed to it. Make sure you assign the correct id of the widget/layout that is behind *FrostedGlass* to the `background` property.
## Example:
<img src="https://github.com/kivy-garden/frostedglass/blob/main/doc/images/kivy_example.png?raw=true">
```kvlang
Image:
id: bg_image
pos_hint: {'center_x': 0.5, 'center_y': 0.5}
source: 'kivy_logo.png'
FrostedGlass:
pos_hint: {'center_x': 0.5, 'center_y': 0.5}
size_hint: (None, None)
size: (180, 130)
background: bg_image
blur_size: 20
saturation: 1.0
luminosity: 1.5
overlay_color: "#FFB9008C"
noise_opacity: 0.15
border_radius: dp(0), dp(100), dp(0), dp(100)
outline_color: "#000000"
outline_width: 1.2
Label:
text: 'FrostedGlass'
pos_hint: {'center_x': 0.5, 'center_y': 0.5}
bold: True
color: 'black'
font_size: dp(25)
```
<br>
## FrostedGlass Showcase:
**You can find the source code in the 🔷[examples folder](https://github.com/kivy-garden/frostedglass/tree/main/examples)🔷**
https://user-images.githubusercontent.com/73297572/214139558-f995ac2c-77bb-4952-a82b-212e2f31d65f.mp4
<br>
## Overview of *FrostedGlass* creation process
To reach the final result of the **FrostedGlass** widget, the steps described in the image below are followed:
<br>
## Features
FrostedGlass is efficient and makes internal optimizations to deliver the best performance while maintaining the quality of the effect, regardless of implementation, for all platforms supported by Kivy.
Overview:
- Automatic effect update, with auto bind to background properties.
- Updates effect only when needed. The effect update will only occur when some background or FrostedGlass property requires the update.
- Avoid unnecessary computation of the effect. If any FrostedGlass widget is not visible, it will not be updated.
- Full control over FrostedGlass properties. The widget is not limited to the frosted glass effect, it can be used simply as an option to achieve gaussian blur of some "background".
<br>
## Guidelines
The FrostedGlass widget is designed to update the effect whenever there is a change to its properties or background properties that requires an effect update, to keep the effect in sync with the background.
But if it doesn't, you can call the `update_effect()` method manually to update the effect.
If calling the `update_effect()` method did not update the effect, you may need to call the `refresh_effect()` method.
<br>
---
## **API**
background
> Target widget/layout that will be used as a background to **FrostedGlass**.
> The recomended way to pass the widget is through the widget/layout **id**.
>
> `background` is defaults to `None`.
<br/>
blur_size
> Size of the gaussian blur aplied to the background.
❗️*Note: Do not pass relative values such as **dp** or **sp**. **FrostedGlass** already
manages this automatically, according to the device's screen density.*
> `blur_size` is defaults to `25`.
<br/>
saturation
> Saturation boost that will be aplied to the background.
>
> `saturation` is defaults to `1.2`.
<br/>
luminosity
> Luminosity boost that will be aplied to the background.
>
> `luminosity` is defaults to `1.3`.
<br/>
overlay_color
> Color/tint overlay that will be aplied over the background.
>
> `overlay_color` is defaults to `[0.5, 0.5, 0.5, 0.35]`.
<br/>
noise_opacity
> Opacity of the noise texture layer.
>
> `noise_opacity` is a defaults to `0.08`.
<br/>
border_radius
> Specifies the radius used for the rounded corners clockwise:
> top-left, top-right, bottom-right, bottom-left.
>
> `border_radius` is defaults to `[0, 0, 0, 0]`.
<br/>
outline_color
> Outline color.
>
> `outline_color` is defaults to `[1, 1, 1, 1]`.
<br/>
outline_width
> Outline width.
>
> `outline_width` is defaults to `1`.
<br/>
update_effect()
> Updates the effect only once with each method call.
❗️*Note: Use this method to update the effect only if **FrostedGlass** doesn't update automatically.*
<br/>
refresh_effect()
> Updates the effect only once with each method call. Sould be used as an alternative, when `update_effect()` doesn't update the effect totally.
❗️*Note: Use this method to update the effect only if **FrostedGlass** doesn't update automatically and `update_effect()` was not enough to update the effect.*
---
<br>
CI
--
Every push or pull request run the [GitHub Action](https://github.com/kivy-garden/flower/actions) CI.
It tests the code on various OS and also generates wheels that can be released on PyPI upon a
tag. Docs are also generated and uploaded to the repo as well as artifacts of the CI.
Contributing
--------------
Check out our [contribution guide](CONTRIBUTING.md) and feel free to improve the FrostedGlass flower.
🔴 If you have a bug or an idea, create a report to help us improve or suggest an idea for this project by opening an issue
🔴 Every contribution is welcome and appreciated!!!
License
---------
This software is released under the terms of the MIT License.
Please see the [LICENSE.txt](LICENSE.txt) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/kivy-garden/frostedglass",
"name": "kivy-garden.frostedglass",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Kivy kivy-garden",
"author": "Kivy",
"author_email": "kivy@kivy.org",
"download_url": "https://files.pythonhosted.org/packages/8f/de/3c308be692e233125e4c00bf56296035fe05d581e447f1e8506e20eb6725/kivy_garden.frostedglass-0.5.0.tar.gz",
"platform": null,
"description": "# FrostedGlass\n\n**FrostedGlass** is a widget with translucent frosted glass effect, that\ncreates a context with the background behind it.\n\nThe effect created is based on the widget/layout passed in as the background.\nYou can control the blur size, saturation, luminosity, overlay color, noise\nopacity, border radius and the outline (color and width).\n\n\n\n\n\n[](https://github.com/kivy-garden/frostedglass/actions)\n[](https://pypi.org/project/kivy-garden.frostedglass/)\n\n## Install\n pip install kivy_garden.frostedglass\n\n## Import\n\n**_python_ import:**\n\n from kivy_garden.frostedglass import FrostedGlass\n\n**or _kvlang_ import:**\n\n #: import FrostedGlass kivy_garden.frostedglass\n\n## Usage\n\n*FrostedGlass* will apply the effect to the background passed to it. Make sure you assign the correct id of the widget/layout that is behind *FrostedGlass* to the `background` property.\n\n## Example:\n\n<img src=\"https://github.com/kivy-garden/frostedglass/blob/main/doc/images/kivy_example.png?raw=true\">\n\n```kvlang\nImage:\n id: bg_image\n pos_hint: {'center_x': 0.5, 'center_y': 0.5}\n source: 'kivy_logo.png'\n\nFrostedGlass:\n pos_hint: {'center_x': 0.5, 'center_y': 0.5}\n size_hint: (None, None)\n size: (180, 130)\n background: bg_image\n blur_size: 20\n saturation: 1.0\n luminosity: 1.5\n overlay_color: \"#FFB9008C\"\n noise_opacity: 0.15\n border_radius: dp(0), dp(100), dp(0), dp(100)\n outline_color: \"#000000\"\n outline_width: 1.2\n Label:\n text: 'FrostedGlass'\n pos_hint: {'center_x': 0.5, 'center_y': 0.5}\n bold: True\n color: 'black'\n font_size: dp(25)\n```\n\n<br>\n\n## FrostedGlass Showcase:\n\n**You can find the source code in the \ud83d\udd37[examples folder](https://github.com/kivy-garden/frostedglass/tree/main/examples)\ud83d\udd37**\n\nhttps://user-images.githubusercontent.com/73297572/214139558-f995ac2c-77bb-4952-a82b-212e2f31d65f.mp4\n\n<br>\n\n## Overview of *FrostedGlass* creation process\n\nTo reach the final result of the **FrostedGlass** widget, the steps described in the image below are followed:\n\n\n\n<br>\n\n## Features\n\nFrostedGlass is efficient and makes internal optimizations to deliver the best performance while maintaining the quality of the effect, regardless of implementation, for all platforms supported by Kivy.\n\nOverview:\n\n- Automatic effect update, with auto bind to background properties.\n- Updates effect only when needed. The effect update will only occur when some background or FrostedGlass property requires the update.\n- Avoid unnecessary computation of the effect. If any FrostedGlass widget is not visible, it will not be updated.\n- Full control over FrostedGlass properties. The widget is not limited to the frosted glass effect, it can be used simply as an option to achieve gaussian blur of some \"background\".\n\n<br>\n\n## Guidelines\n\nThe FrostedGlass widget is designed to update the effect whenever there is a change to its properties or background properties that requires an effect update, to keep the effect in sync with the background. \n\nBut if it doesn't, you can call the `update_effect()` method manually to update the effect.\n\nIf calling the `update_effect()` method did not update the effect, you may need to call the `refresh_effect()` method.\n\n<br>\n\n---\n\n## **API**\n\n background\n\n> Target widget/layout that will be used as a background to **FrostedGlass**.\n> The recomended way to pass the widget is through the widget/layout **id**.\n> \n> `background` is defaults to `None`.\n\n<br/>\n\n blur_size\n\n> Size of the gaussian blur aplied to the background.\n\n\u2757\ufe0f*Note: Do not pass relative values such as **dp** or **sp**. **FrostedGlass** already\n manages this automatically, according to the device's screen density.*\n\n> `blur_size` is defaults to `25`.\n\n<br/>\n\n saturation\n\n> Saturation boost that will be aplied to the background.\n> \n> `saturation` is defaults to `1.2`.\n\n<br/>\n\n luminosity\n\n> Luminosity boost that will be aplied to the background.\n> \n> `luminosity` is defaults to `1.3`.\n\n\n<br/>\n\n overlay_color\n\n> Color/tint overlay that will be aplied over the background.\n> \n> `overlay_color` is defaults to `[0.5, 0.5, 0.5, 0.35]`.\n\n<br/>\n\n noise_opacity\n\n> Opacity of the noise texture layer.\n> \n> `noise_opacity` is a defaults to `0.08`.\n\n<br/>\n\n border_radius\n\n> Specifies the radius used for the rounded corners clockwise:\n> top-left, top-right, bottom-right, bottom-left.\n> \n> `border_radius` is defaults to `[0, 0, 0, 0]`.\n\n<br/>\n\n outline_color\n\n> Outline color.\n> \n> `outline_color` is defaults to `[1, 1, 1, 1]`.\n\n<br/>\n\n outline_width\n\n> Outline width.\n> \n> `outline_width` is defaults to `1`.\n\n<br/>\n\n update_effect()\n\n> Updates the effect only once with each method call.\n\n\u2757\ufe0f*Note: Use this method to update the effect only if **FrostedGlass** doesn't update automatically.*\n\n<br/>\n\n refresh_effect()\n\n> Updates the effect only once with each method call. Sould be used as an alternative, when `update_effect()` doesn't update the effect totally.\n\n\u2757\ufe0f*Note: Use this method to update the effect only if **FrostedGlass** doesn't update automatically and `update_effect()` was not enough to update the effect.*\n\n---\n\n<br>\n\nCI\n--\n\nEvery push or pull request run the [GitHub Action](https://github.com/kivy-garden/flower/actions) CI.\nIt tests the code on various OS and also generates wheels that can be released on PyPI upon a\ntag. Docs are also generated and uploaded to the repo as well as artifacts of the CI.\n\nContributing\n--------------\n\nCheck out our [contribution guide](CONTRIBUTING.md) and feel free to improve the FrostedGlass flower.\n\n\ud83d\udd34 If you have a bug or an idea, create a report to help us improve or suggest an idea for this project by opening an issue\n\n\ud83d\udd34 Every contribution is welcome and appreciated!!!\n\nLicense\n---------\n\nThis software is released under the terms of the MIT License.\nPlease see the [LICENSE.txt](LICENSE.txt) file.\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "FrostedGlass is a Kivy widget with frosted glass effect.",
"version": "0.5.0",
"project_urls": {
"Bug Reports": "https://github.com/kivy-garden/frostedglass/issues",
"Homepage": "https://github.com/kivy-garden/frostedglass",
"Source": "https://github.com/kivy-garden/frostedglass"
},
"split_keywords": [
"kivy",
"kivy-garden"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "64fa941b67bfbd00fa20a2f29d4ff5a10da7ec613b042babb84b867a62203494",
"md5": "e35ce246dc597319db60dd339925daff",
"sha256": "b201e46c72123334843011f86bb98d74b35ee60446084ee28f06c749bf3e96f3"
},
"downloads": -1,
"filename": "kivy_garden.frostedglass-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e35ce246dc597319db60dd339925daff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10526,
"upload_time": "2023-05-28T15:17:28",
"upload_time_iso_8601": "2023-05-28T15:17:28.017541Z",
"url": "https://files.pythonhosted.org/packages/64/fa/941b67bfbd00fa20a2f29d4ff5a10da7ec613b042babb84b867a62203494/kivy_garden.frostedglass-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8fde3c308be692e233125e4c00bf56296035fe05d581e447f1e8506e20eb6725",
"md5": "5b395a380c5c4edad961469a8397b0f2",
"sha256": "37fd67ce194ebbabf1596f67792352b5121a9609205c6666d3bd9c9cf69527ea"
},
"downloads": -1,
"filename": "kivy_garden.frostedglass-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "5b395a380c5c4edad961469a8397b0f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12195,
"upload_time": "2023-05-28T15:17:29",
"upload_time_iso_8601": "2023-05-28T15:17:29.834231Z",
"url": "https://files.pythonhosted.org/packages/8f/de/3c308be692e233125e4c00bf56296035fe05d581e447f1e8506e20eb6725/kivy_garden.frostedglass-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-28 15:17:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kivy-garden",
"github_project": "frostedglass",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kivy-garden.frostedglass"
}
JSON
