The Android Developer Challenge is back! Submit your idea before December 2.

ImageReference

open class ImageReference : VersionedParcelable
kotlin.Any
   ↳ androidx.car.cluster.navigation.ImageReference

Reference to an image. This class encapsulates a 'content://' style URI plus metadata that allows consumers to know the image they will receive and how to handle it.

  • Sizing: Producers will always provide an image "original" size which defines the image aspect ratio. When requesting these images, consumers must always specify a desired size (width and height) based on UI available space and the provided aspect ration. Producers can use this "requested" size to select the best version of the requested image, and producers can optionally resize the image to exactly match the "requested" size provided, but consumers should not assume that the received image will match such size. Instead, consumers should always assume that the image will require additional scaling.
  • Content: Producers should avoid including margins around the image content.
  • Format: Content URI must reference a file with MIME type 'image/png', 'image/jpeg' or 'image/bmp' (vector images are not supported).
  • Color: Images can be either "tintable" or not. A "tintable" image is such that all its content is defined in its alpha channel, while its color (all other channels) can be altered without losing information (e.g.: icons). A non "tintable" images contains information in all its channels (e.g.: photos).
  • Caching: Given the same image reference and the same requested size, producers must return the exact same image. This means that it should be safe for the consumer to cache an image once downloaded and use this image reference plus requested size as key, for as long as they need. If a producer needs to provide a different version of a certain image, they must provide a different image reference (e.g. producers can opt to include version information as part of the content URI).

Summary

Nested classes

Builder for creating an ImageReference.

Public methods

open Boolean
equals(other: Any?)

open Uri?
getContentUri(width: Int, height: Int)

Returns a fully formed Uri that can be used to retrieve the actual image, including size constraints, or null if this image reference is not properly formed.

open Int

Returns the image height, which should only be used to determine the image aspect ratio.

open Int

Returns the image width, which should only be used to determine the image aspect ratio.

open Int

open Boolean

Returns whether this image is "tintable" or not.

open String

Public methods

equals

open fun equals(other: Any?): Boolean

getContentUri

@Nullable open fun getContentUri(width: Int, height: Int): Uri?

Returns a fully formed Uri that can be used to retrieve the actual image, including size constraints, or null if this image reference is not properly formed.

Producers can optionally use these size constraints to provide an optimized version of the image, but the resulting image might still not match the requested size.

Consumers must confirm the size of the received image and scale it proportionally ( maintaining the aspect ratio of the received image) if it doesn't match the desired dimensions.

Parameters
width Int: desired maximum width (must be greater than 0)
height Int: desired maximum height (must be greater than 0)
Return
Uri?: fully formed Uri, or null if this image reference can not be used.

getOriginalHeight

open fun getOriginalHeight(): Int

Returns the image height, which should only be used to determine the image aspect ratio.

getOriginalWidth

open fun getOriginalWidth(): Int

Returns the image width, which should only be used to determine the image aspect ratio.

hashCode

open fun hashCode(): Int

isTintable

open fun isTintable(): Boolean

Returns whether this image is "tintable" or not. An image is "tintable" when all its content is defined in its alpha-channel, designed to be colorized (e.g. using android.graphics.PorterDuff.Mode#SRC_ATOP image composition).

toString

open fun toString(): String