Preview.kt
/*
* Copyright 2023 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.wear.tiles.tooling.preview
import android.content.Context
import androidx.annotation.FloatRange
import androidx.wear.tooling.preview.devices.WearDevice
import androidx.wear.tooling.preview.devices.WearDevices
/**
* The annotation that marks Tile preview components that should have a visual preview in the
* Android Studio preview panel. Tile preview components are methods that take an optional [Context]
* parameter and return a [TilePreviewData]. Methods annotated with [Preview] must be top level
* declarations or in a top level class with a default constructor.
*
* For example:
* ```kotlin
* @Preview
* fun myTilePreview(): TilePreviewData {
* return TilePreviewData { request -> myTile(request) }
* }
* ```
* or:
* ```kotlin
* @Preview
* fun myTilePreview(context: Context): TilePreviewData {
* return TilePreviewData { request -> myTile(request, context) }
* }
* ```
*
* Because of the way previews are rendered within Android Studio, they are lightweight and don't
* require the whole Android framework to render them. However, this comes with the following
* limitations:
* * No network access
* * No file access
* * Some [Context] APIs may not be fully available, such as launching activities or retrieving
* services
*
* For more information, see
* https://developer.android.com/jetpack/compose/tooling/previews#preview-limitations
*
* The annotation contains a number of parameters that allow to define the way the Tile will be
* rendered within the preview. The passed parameters are only read by Studio when rendering the
* preview.
*
* @param name Display name of this preview allowing to identify it in the panel.
* @param group Group name for this @[Preview]. This allows grouping them in the UI and
* displaying only one or more of them.
* @param locale Current user preference for the locale, corresponding to
* [locale](https://d.android.com/guide/topics/resources/providing-resources.html#LocaleQualifier)
* resource qualifier. By default, the `default` folder will be used.
* @param device Device identifier indicating the device to use in the preview. For example
* "id:wearos_small_round".See the available devices in [WearDevices].
* @param fontScale User preference for the linear scaling factor for fonts, relative to the base
* density scaling.
*/
@Retention(AnnotationRetention.BINARY)
@Target(
AnnotationTarget.ANNOTATION_CLASS,
AnnotationTarget.FUNCTION
)
@Repeatable
@MustBeDocumented
annotation class Preview(
val name: String = "",
val group: String = "",
val locale: String = "",
@WearDevice val device: String = WearDevices.SMALL_ROUND,
@FloatRange(from = 0.01) val fontScale: Float = 1f,
)