Shadow errors

Package: com.zedalpha.shadowgadgets.view

Errors for which the library may log or throw, depending on the values of suppressLogs and throwOnUnhandledErrors.

ShadowException

^(docs)

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

The Exception class for shadow errors.

Errors

Currently these comprise solely configuration errors, and all can be remedied at design time except the very last one.

Each error description is headed by its message.

Child shadows

The first two apply to shadows on targets that are children of ViewGroups.

• Color compat shadows without the clip feature enabled must use the Background plane

  If you're using color compat by itself in order to avoid the clip overhead, you must use the Background plane since the original defect will still be present.

• Inline shadows cannot have [target.clipToOutline=true] [or] [parent.clipChildren=true]

  Inline shadows are actually drawn in the target's routine rather than the parent's, so they're subject to any clips that affect the target's draw. Both the target's clipToOutline and its parent's clipChildren must be false.

  If you have a setup in which those settings cannot be accommodated, the ShadowsViewGroups all have a special functionality available: takeOverDrawForInlineChildShadows, an explanation for which can be found on the ShadowPlane page.

Root shadows

The last four apply only to root Views, e.g., those you add directly to WindowManager yourself.

• Shadows on root Views must use the Inline plane

  The Foreground and Background planes live in a target's parent ViewGroup, which doesn't exist when the target is at the top of the hierarchy.

• Color compat shadows on root Views require that the clip feature be enabled too

  Since we can't use the Background plane here, we're forced to use the clip too.

• Shadows on root Views cannot have target.clipToOutline=true

  Same restrictions as for the child Inline shadows, but without the parent.

• Library shadows are not available on non-ViewGroup roots [on API levels 21, 22, and 28] | [with the fallback draw method currently in use]

  The | here means one or the other, whichever check hits first.

  This particular error is possible only on API levels 28 and below.

  The failure with the fallback method is the only error state that cannot be avoided with design-time alterations; i.e., on an arbitrary device, you can't know if it'll happen until it happens. This is also the main reason for the ShadowMode enum and its helper extension, View.doOnShadowModeChange, which is basically an error callback.