UserStyleSetting

sealed class UserStyleSetting

Known direct subclasses
UserStyleSetting.BooleanUserStyleSetting

A BooleanUserStyleSetting represents a setting with a true and a false setting.

UserStyleSetting.ComplicationSlotsUserStyleSetting

ComplicationSlotsUserStyleSetting is the recommended UserStyleSetting for representing complication slot configuration, options such as the number of active complication slots, their location, etc...

UserStyleSetting.CustomValueUserStyleSetting

An application specific style setting.

UserStyleSetting.DoubleRangeUserStyleSetting

A DoubleRangeUserStyleSetting represents a setting with a Double value in the range [minimumValue .. maximumValue].

UserStyleSetting.LargeCustomValueUserStyleSetting

An application specific style setting which supports a larger maximum size than CustomValueUserStyleSetting.

UserStyleSetting.ListUserStyleSetting

A ListUserStyleSetting represents a setting with options selected from a List.

UserStyleSetting.LongRangeUserStyleSetting

A LongRangeUserStyleSetting represents a setting with a Long value in the range minimumValue .. maximumValue.


Watch faces often have user configurable styles, the definition of what is a style is left up to the watch face but it typically incorporates a variety of settings such as: color, visual theme for watch hands, font, tick shape, complication slots, audio elements, etc...

A UserStyleSetting represents one of these dimensions. See also UserStyleSchema which defines the list of UserStyleSettings provided by the watch face.

Styling data gets shared with the companion phone to support editors (typically over bluetooth), as a result the size of serialized UserStyleSettings could become an issue if large.

It is possible to define a hierarchy of styles, (e.g. a watch face might have support a number of different looks, each with their own settings). A hierarchy is defined by setting child styles in ListUserStyleSetting.ListOption.childSettings. A setting is deemed to be active if it's either in the top level of the tree, or if it's the child of an Option selected by the user in the UserStyle. In a hierarchy multiple ComplicationSlotsUserStyleSetting are allowed but only one can be active at any time, for more details see UserStyleSchema.findComplicationSlotsOptionForUserStyle.

Summary

Nested types

A BooleanUserStyleSetting represents a setting with a true and a false setting.

Represents a true or false option in the BooleanUserStyleSetting.

ComplicationSlotsUserStyleSetting is the recommended UserStyleSetting for representing complication slot configuration, options such as the number of active complication slots, their location, etc...

Overrides to be applied to the corresponding androidx.wear.watchface.ComplicationSlot's initial config (as specified in it's constructor) when the setting is selected.

Constructs a ComplicationSlotOverlay.Builder.

Represents an override to the initial androidx.wear.watchface.ComplicationSlotsManager configuration.

An application specific style setting.

An application specific custom value.

A DoubleRangeUserStyleSetting represents a setting with a Double value in the range [minimumValue .. maximumValue].

Represents an option as a Double in the range minimumValue .. maximumValue.

Machine readable identifier for UserStyleSettings.

An application specific style setting which supports a larger maximum size than CustomValueUserStyleSetting.

An application specific custom value.

A ListUserStyleSetting represents a setting with options selected from a List.

Represents choice within a ListUserStyleSetting, these must be enumerated up front.

A LongRangeUserStyleSetting represents a setting with a Long value in the range minimumValue .. maximumValue.

Represents an option a Long in the range minimumValue .. maximumValue.

Represents a choice within a style setting which can either be an option from the list or a an arbitrary value depending on the nature of the style setting.

Machine readable identifier for Options.

Optional data for an on watch face editor (not the companion editor).

Public functions

open operator Boolean
equals(other: Any?)
open UserStyleSetting.Option

Translates an option name into an option.

open Int
open String

Public properties

Collection<WatchFaceLayer>

Used by the style configuration UI.

UserStyleSetting.Option

Returns the default for when the user hasn't selected an option.

Int

The default option index, used if nothing has been selected within the options list.

CharSequence

Localized description string displayed under the displayName.

CharSequence

Localized human readable name for the element, used in the userStyle selection UI.

Icon?

Icon for use in the companion editor style selection UI.

UserStyleSetting.Id

Identifier for the element, must be unique.

List<UserStyleSetting.Option>

List of options for this UserStyleSetting.

UserStyleSetting.WatchFaceEditorData?

Optional data for an on watch face editor, this will not be sent to the companion and its contents may be used in preference to other fields by an on watch face editor.

Public functions

equals

open operator fun equals(other: Any?): Boolean

getOptionForId

Added in 1.0.0
open fun getOptionForId(optionId: UserStyleSetting.Option.Id): UserStyleSetting.Option

Translates an option name into an option. This will need to be overridden for userStyle categories that can't sensibly be fully enumerated (e.g. a full 24-bit color picker).

Parameters
optionId: UserStyleSetting.Option.Id

The Option.Id of the option

Returns
UserStyleSetting.Option

An Option corresponding to the name. This could either be one of the options from UserStyleSettings or a newly constructed Option depending on the nature of the UserStyleSetting. If optionName is unrecognized then the default value for the setting should be returned.

hashCode

open fun hashCode(): Int

toString

open fun toString(): String

Public properties

affectedWatchFaceLayers

Added in 1.0.0
val affectedWatchFaceLayersCollection<WatchFaceLayer>

Used by the style configuration UI. Describes which rendering layers this style affects.

defaultOption

Added in 1.0.0
val defaultOptionUserStyleSetting.Option

Returns the default for when the user hasn't selected an option.

defaultOptionIndex

Added in 1.0.0
val defaultOptionIndexInt

The default option index, used if nothing has been selected within the options list.

description

Added in 1.0.0
val descriptionCharSequence

Localized description string displayed under the displayName.

displayName

Added in 1.0.0
val displayNameCharSequence

Localized human readable name for the element, used in the userStyle selection UI.

icon

Added in 1.0.0
val iconIcon?

Icon for use in the companion editor style selection UI.

id

Added in 1.0.0
val idUserStyleSetting.Id

Identifier for the element, must be unique. Styling data gets shared with the companion (typically via bluetooth) so size is a consideration and short ids are encouraged. There is a maximum length see UserStyleSetting.Id.MAX_LENGTH.

options

Added in 1.0.0
val optionsList<UserStyleSetting.Option>

List of options for this UserStyleSetting. Depending on the type of UserStyleSetting this may be an exhaustive list, or just examples to populate a ListView in case the UserStyleSetting isn't supported by the UI (e.g. a new WatchFace with an old companion).

watchFaceEditorData

Added in 1.1.0
val watchFaceEditorDataUserStyleSetting.WatchFaceEditorData?

Optional data for an on watch face editor, this will not be sent to the companion and its contents may be used in preference to other fields by an on watch face editor.