Stay organized with collections
Save and categorize content based on your preferences.
OnThermalHeadroomChangedListener
interface OnThermalHeadroomChangedListener
Listener passed to android.os.PowerManager#addThermalHeadroomListener and PowerManager.removeThermalHeadroomListener to notify caller of Thermal headroom or thresholds changes.
Summary
| Public methods |
| abstract Unit |
Called when overall thermal headroom or headroom thresholds have significantly changed that requires action.
|
Public methods
onThermalHeadroomChanged
abstract fun onThermalHeadroomChanged(
headroom: Float,
forecastHeadroom: Float,
forecastSeconds: Int,
thresholds: MutableMap<Int!, Float!>
): Unit
Called when overall thermal headroom or headroom thresholds have significantly changed that requires action.
This may not be used to fully replace the getThermalHeadroom(int) API as it will only notify on one of the conditions below that will significantly change one or both values of current headroom and headroom thresholds since previous callback: 1. thermal throttling events: when the skin temperature has cross any of the thresholds and there isn't a previous callback in a short time ago with similar values. 2. skin temperature threshold change events: note that if the absolute °C threshold values change in a way that does not significantly change the current headroom nor headroom thresholds, it will not trigger any callback. The client should not need to take action in such case since the difference from temperature vs threshold hasn't changed.
By API version 36, it provides a forecast in the same call for developer's convenience based on a forecastSeconds defined by the device, which can be static or dynamic varied by OEM. Be aware that it will not notify on forecast temperature change but the events mentioned above. So periodically polling against getThermalHeadroom(int) API should still be used to actively monitor temperature forecast in advance.
This serves as a more advanced option compared to thermal status listener, where the latter will only notify on thermal throttling events with status update.
| Parameters |
headroom |
Float: current headroom Value is 0.0f or greater |
forecastHeadroom |
Float: forecasted headroom in future Value is 0.0f or greater |
forecastSeconds |
Int: how many seconds in the future used in forecast Value is 0 or greater |
thresholds |
MutableMap<Int!, Float!>: new headroom thresholds, see getThermalHeadroomThresholds() This value cannot be null. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-08-20 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-20 UTC."],[],[],null,["# PowerManager.OnThermalHeadroomChangedListener\n\nAdded in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)\n\nOnThermalHeadroomChangedListener\n================================\n\n*** ** * ** ***\n\nKotlin \\|[Java](/reference/android/os/PowerManager.OnThermalHeadroomChangedListener \"View this page in Java\") \n\n```\ninterface OnThermalHeadroomChangedListener\n```\n\n|---------------------------------------------------------------|\n| [android.os.PowerManager.OnThermalHeadroomChangedListener](#) |\n\nListener passed to android.os.PowerManager#addThermalHeadroomListener and [PowerManager.removeThermalHeadroomListener](/reference/kotlin/android/os/PowerManager#removeThermalHeadroomListener(android.os.PowerManager.OnThermalHeadroomChangedListener)) to notify caller of Thermal headroom or thresholds changes.\n\nSummary\n-------\n\n| Public methods ||\n|---------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| abstract [Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html) | [onThermalHeadroomChanged](#onThermalHeadroomChanged(kotlin.Float,%20kotlin.Float,%20kotlin.Int,%20kotlin.collections.MutableMap))`(`headroom:` `[Float](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html)`, `forecastHeadroom:` `[Float](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html)`, `forecastSeconds:` `[Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)`, `thresholds:` `[MutableMap](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-mutable-map/index.html)\u003c[Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)!,` `[Float](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html)!\u003e`)` Called when overall thermal headroom or headroom thresholds have significantly changed that requires action. |\n\nPublic methods\n--------------\n\n### onThermalHeadroomChanged\n\nAdded in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nabstract fun onThermalHeadroomChanged(\n headroom: Float, \n forecastHeadroom: Float, \n forecastSeconds: Int, \n thresholds: MutableMap\u003cInt!, Float!\u003e\n): Unit\n```\n\nCalled when overall thermal headroom or headroom thresholds have significantly changed that requires action.\n\nThis may not be used to fully replace the [getThermalHeadroom(int)](/reference/kotlin/android/os/PowerManager#getThermalHeadroom(kotlin.Int)) API as it will only notify on one of the conditions below that will significantly change one or both values of current headroom and headroom thresholds since previous callback: 1. thermal throttling events: when the skin temperature has cross any of the thresholds and there isn't a previous callback in a short time ago with similar values. 2. skin temperature threshold change events: note that if the absolute °C threshold values change in a way that does not significantly change the current headroom nor headroom thresholds, it will not trigger any callback. The client should not need to take action in such case since the difference from temperature vs threshold hasn't changed.\n\nBy API version 36, it provides a forecast in the same call for developer's convenience based on a `forecastSeconds` defined by the device, which can be static or dynamic varied by OEM. Be aware that it will not notify on forecast temperature change but the events mentioned above. So periodically polling against [getThermalHeadroom(int)](/reference/kotlin/android/os/PowerManager#getThermalHeadroom(kotlin.Int)) API should still be used to actively monitor temperature forecast in advance.\n\nThis serves as a more advanced option compared to thermal status listener, where the latter will only notify on thermal throttling events with status update.\n\n| Parameters ||\n|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `headroom` | [Float](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html): current headroom Value is 0.0f or greater |\n| `forecastHeadroom` | [Float](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html): forecasted headroom in future Value is 0.0f or greater |\n| `forecastSeconds` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): how many seconds in the future used in forecast Value is 0 or greater |\n| `thresholds` | [MutableMap](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-mutable-map/index.html)\\\u003c[Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)!, [Float](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html)!\\\u003e: new headroom thresholds, see [getThermalHeadroomThresholds()](/reference/kotlin/android/os/PowerManager#getThermalHeadroomThresholds()) This value cannot be `null`. |"]]
