Add documentation for progress bar customization on Android - #1297
Add documentation for progress bar customization on Android#1297inukiwi wants to merge 8 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation to the Companion Apps docs describing the new Android 16.0+ “progress-centric” notification progress bar customization options, including an example and screenshot.
Changes:
- Document progress bar styling options (segments, points, and icons/colors) for Android 16.0+ notifications.
- Add a YAML automation example demonstrating the new parameters.
- Add a screenshot asset illustrating the customized progress bar result.
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/notifications/basic.md | Adds a new “Styling the progress bar” section with supported parameters, caveats, and an example. |
| static/assets/android/progress_bar_customized.png | Adds the screenshot referenced by the new documentation section. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
|
Feedback has been implemented |
Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
|
a merge conflict has appeared |
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
|
This specific feature is not ready to be released yet so I think it's better to just move on with #1303. |
| - `progress_start_icon`: Icon displayed at the start of the progress bar. For example: `"mdi:battery-10"`. | ||
| - **Format**: Material Design Icons only, use format `mdi:icon-name` (for example, `mdi:home` or `mdi:download`). | ||
| - `progress_end_icon`: Icon displayed at the end of the progress bar. For example: `"mdi:battery"` |
There was a problem hiding this comment.
Do we need to define start and end? Can't we make it generic so the user defines a bunch of points and we just render based on that definition?
There was a problem hiding this comment.
Think of the "Point" as an object containing:
- Length
- Icon
- color
- maybe more properties..
There was a problem hiding this comment.
Would be nice to have a "accessibility_name" as well for people using voice over
There was a problem hiding this comment.
We could probably make it more generic, but if the goal is to make it easier for the end user I think it would make things more complicated by explaining all the restrictions.
A point can only have a position and color, it will always be rendered as a small dot on the progress bar and can't have any icon. There can be unlimited points on a progress bar.
The icons are placed next to the progress bar and not on it, so they look very different from points.
The exception to that could be the tracker icon, which is placed on the progress bar, but it's still different from a point.
In the image below you can see the difference: the arrow and the car are trackers, the pink square is a point.
There was a problem hiding this comment.
Understood, but iOS has more flexibility in this situation (for the first time 🙌🏻), when this gets implemented in iOS we could allow users to customize their points, for example:
In a "waiting for package delivery" scenario:
Point 1:
- Warehouse icon
- Color blue
- length 0 (if I understood correctly this would mean the start)
- accessibility name: At warehouse
Point 2:
- Truck icon
- Color brown
- Length 10
- accessibility name: On it's way
Point 3:
- House icon
- Color green
- Length 20
- accessibility name: Delivered
I think this way we keep it more future proof, what do you think? We can have default values as well so the user does not need to fill everything
There was a problem hiding this comment.
Depends how you write it, I'd say we explain in a simple manner + examples + one image pointing to the part of the UI the YAML refers to (have a UI in HA instead of yaml would be lovely but... out of scope).
"To define your notification progress indicators you just need to provide an array of points, look at the example below"
<yaml example>
"The points located at position 0 or at progress_max can define icons to be visible at the beginning and end of the progress bar, the other points do not support icons and will be displayed along the way."
"You can define only 1 point-tracker to indicate the progress"
"Check how it looks like in a package delivery scenario following the image below"
<Mocked notification image with poins overlayed>
There was a problem hiding this comment.
My example above has the assumption we add a key "is_tracker" or something like that
There was a problem hiding this comment.
I would like to see the two proposal face to face to decide. I agree that point seems more generic but at the same the logic to display before and after the progress bar is not friendly
There was a problem hiding this comment.
Perhaps thats where we draw the line and we start differentiating, android specific use cases and iOS specific. If the original proposal is implemented I can make it happen in iOS as well and then for more customization a third type can be introduced just for iOS.
I hope google does not make this more flexible in the future, otherwise the original proposal wont be able to accomodate the changes.
There was a problem hiding this comment.
I've created a draft of what the documentation would look like in my opinion if we go for a points-only approach: inukiwi@0f88d27
It doesn't make it too complex in this form, but it doesn't cover details like the tracker point looking different from other points etc.
jpelgrom
left a comment
jpelgrom
left a comment
There was a problem hiding this comment.
Don't want to distract too much from the ongoing discussion and agree with #1297 (comment), but here are some more minor suggestions.
Proposed change
This feature adds support for progress bar customization on Android 16.0+ devices, as shown here.
Screenshot of an example notification:
Type of change
Checklist
Additional information