Built in Settings Page

This template contains extensible built in settings/user preference management. It's very easy to to add new settings items within 5 mins. All you have to do is, prepare PrefItem<T> data class and feed it to a built in PrefItemView<T>.

PrefItem Data Class

The PrefItem data class serves as the model for a single preference. It encapsulates the following information:

data class PrefItem<T>(
	val title: String,
	val icon: ImageVector,
	val key: Preferences.Key<T>,
	val value: T,
	val color: Color
)

• title: The human-readable label for the preference.

• icon: The icon associated with the preference, displayed visually.

• key: A unique identifier for the preference, used for storage and retrieval.

• value: The current value of the preference. You can consider it as a default value when you initialize the data class.

• color: The color used for the preference's text and icon, providing visual differentiation.

PrefItemView Composable Function

@Composable
fun <T> PrefItemView(
	pref: PrefItem<T>,
	values: Set<T> = setOf(),
	prefType: PrefType = PrefType.GENERIC_ACTION,
	onPrefSelected: (PrefItem<T>) -> Unit = {},
	onClick: (pref: PrefItem<T>) -> Unit = {}
){..}

The PrefItemView composable function is responsible for rendering a single settings item on the screen based on a provided PrefItem object. It offers the following key features:

• PrefItem: The PrefItem<T> instance that defines the preference's characteristics.

• values: An optional set of values that can be selected for dropdown-style preferences.

• prefType: The type of the preference, either DROPDOWN or GENERIC_ACTION.

  • DROPDOWN serves as a regular preference where user can change a setting by choosing an option.

  PrefItemView(
      pref = prefDefinitions.theme,
      prefType = PrefType.DROPDOWN,
      values = setOf(
         AppThemes.DEFAULT.name,
         AppThemes.DARK.name,
         AppThemes.LIGHT.name
      ),
      onPrefSelected = {
         prefVM.updatePref(it) // save new value using PrefVM viewmodel
         visible = false
      }
  )

  • GENERIC_ACTION is where you'll apply your custom action. IE

    PrefItemView(
        pref = prefDefinitions.profile
    ) {
        snackbar.show("Profile Clicked!")
    }

• onPrefSelected: A callback function that is invoked when the user selects a new value for the preference.

• onClick: An optional callback function that is invoked when the user clicks on the preference item (for GENERIC_ACTION type).

The PrefItemView displays the preference's title, icon, and current value. For dropdown-style preferences, it shows a dropdown menu with available options. When the user selects a new value or clicks on the item, the appropriate callback function is triggered.

Code Flow

1. Create a PrefItem object: Define a PrefItem instance with the desired title, icon, key, value, and color.

2. Pass the PrefItem to PrefItemView: Provide the PrefItem object as an argument to the PrefItemView composable function.

3. Customize appearance and behavior: Optionally set the values, prefType, onPrefSelected, and onClick parameters to tailor the PrefItemView to your specific needs.

4. Handle user interactions: Implement the onPrefSelected and onClick callback functions to handle user input and update the preference's value accordingly.

Adding New Settings Items

To add a new settings item, follow these steps:

1. Create a PrefItem object: Define a new PrefItem instance with the appropriate properties.

2. Include the PrefItem in the PrefSection: Add the PrefItem to the desired PrefSection within the SettingsScreen composable.

3. Customize the PrefItemView: If necessary, modify the PrefItemView parameters to customize the appearance and behavior of the new item.

By following these steps, you can easily create and manage various settings items within your application.