Package: com.zedalpha.shadowgadgets.view

These features are interwoven rather tightly into the core functionalities, so they're considered experimental for now, until we can be relatively certain that they won't blow up everyone's projects.

^(docs)

@RequiresOptIn("Nonfinal API. May be altered, moved or removed without notice.")
public annotation class ExperimentalShadowGadgets

A new annotation for the following and future features.

^(docs)

@ExperimentalShadowGadgets
public object ShadowGadgets

A convenience object to hold one-off properties and such. It currently has just the two flags:

^(docs)

@ExperimentalShadowGadgets
public var suppressLogs: Boolean = false

This turns off debug logs for known error states. There are no release logs.

^(docs)

@ExperimentalShadowGadgets
public var throwOnUnhandledErrors: Boolean = false

The library is now pro-Exception in lieu of failing silently, but that's a hefty change to drop suddenly, so it will sit behind this flag for the time being. This should be set as early as possible, like in an Application subclass, as is shown in the demo app's DemoApplication.

When this is true, known error states will throw ShadowExceptions if the target View has no doOnShadowModeChange handler set. If it does, it's assumed that ShadowMode.Errors will be handled there.

^(docs)

@ExperimentalShadowGadgets
public class ShadowException(message: String) : RuntimeException(message)

A general Exception class for known error states.

^(docs)

@ExperimentalShadowGadgets
public enum class ShadowMode { Native, Library, Error }

An enum describing the possible shadow modes.

• Native: The native, broken shadow is still in place.
• Library: A library shadow is attached and working normally.
• Error: The library encountered an issue and has disabled the shadow.

^(docs)

@ExperimentalShadowGadgets
public val View.shadowMode: ShadowMode

An extension that returns the receiver's current ShadowMode.

^(docs)

@ExperimentalShadowGadgets
public fun View.doOnShadowModeChange(action: (View.(mode: ShadowMode) -> Unit)?)

A callback that's meant mainly for error handling.

All known error states are generally fixable with simple design-time property adjustments except for one: potential failures on non-ViewGroup roots, e.g., ImageViews added directly to WindowManager. There's no way to know all the specific environments in which they may fail, so this runtime callback is offered as an opportunity for the user to apply their own fallback.

It is recommended to handle this in the same manner as View updates in recycling Adapters: always account for all possible states, since multi-property updates could potentially involve invalid intermediate states. For example, don't do this:

target.doOnShadowModeChange { mode ->
    if (mode == ShadowMode.Disabled) {
        foreground = FallbackShadowDrawable()
    }
}

Instead, do this:

target.doOnShadowModeChange { mode ->
    foreground =
        if (mode == ShadowMode.Disabled) {
            FallbackShadowDrawable()
        } else {
            null
        }
}

…which is precisely how the demo app handles this in its RootTopic class.

These functions efficiently update multiple shadow properties at once, deferring potentially redundant internal operations until they complete.

^(docs)

@ExperimentalShadowGadgets
public fun View.updateShadow(block: View.() -> Unit)

This is the base function which takes a block in which to modify library shadow properties. Certain internal library mechanisms are suspended until block completes in order to avoid useless or repetitive work.

A good example of usage can be found in that same RootTopic class.

^(docs)

@ExperimentalShadowGadgets
public fun View.resetShadow()

A convenience that resets all of the properties of a target's library shadow, effectively disabling it and restoring the native (broken) one. Mainly meant for testing and debugging.