{"id":13610706,"url":"https://github.com/marcauberer/simple-settings","last_synced_at":"2025-08-20T18:32:55.117Z","repository":{"id":36977616,"uuid":"263408016","full_name":"marcauberer/simple-settings","owner":"marcauberer","description":"⚙️ Simple Settings library for Android","archived":false,"fork":false,"pushed_at":"2024-12-17T07:44:13.000Z","size":3621,"stargazers_count":44,"open_issues_count":7,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-17T08:39:42.163Z","etag":null,"topics":["android","kotlin","library","material-design","settings","simple"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcauberer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["marcauberer"],"custom":"https://www.paypal.me/marcauberer"}},"created_at":"2020-05-12T17:41:02.000Z","updated_at":"2024-08-05T13:35:44.000Z","dependencies_parsed_at":"2023-09-25T10:39:47.361Z","dependency_job_id":"24af606e-c944-4d8a-80dd-3a04eb8947d5","html_url":"https://github.com/marcauberer/simple-settings","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcauberer%2Fsimple-settings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcauberer%2Fsimple-settings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcauberer%2Fsimple-settings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcauberer%2Fsimple-settings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcauberer","download_url":"https://codeload.github.com/marcauberer/simple-settings/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230445926,"owners_count":18227060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","kotlin","library","material-design","settings","simple"],"created_at":"2024-08-01T19:01:47.234Z","updated_at":"2024-12-19T14:07:19.164Z","avatar_url":"https://github.com/marcauberer.png","language":"Kotlin","funding_links":["https://github.com/sponsors/marcauberer","https://www.paypal.me/marcauberer"],"categories":["Kotlin"],"sub_categories":[],"readme":"# Simple Settings Library for Android\n[![Maven Central](https://img.shields.io/maven-central/v/com.chillibits/simplesettings.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.chillibits%22%20AND%20a:%22simplesettings%22)\n![GitHub release](https://img.shields.io/github/v/release/marcauberer/simple-settings?include_prereleases)\n![Android CI](https://github.com/marcauberer/simple-settings/workflows/Android%20CI/badge.svg)\n[![API](https://img.shields.io/badge/API-21%2B-red.svg?style=flat)](https://android-arsenal.com/api?level=21)\n[![Article on Medium](https://aleen42.github.io/badges/src/medium.svg)](https://medium.com/swlh/simple-settings-library-build-a-settings-screen-in-seconds-5b6394fbd2fc)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\nSimple Settings is a library, which provides a simple to use, lightweight solution to create a settings screen without any boilerplate code. This behaviour saves cost, time and effort.\n\n## Try it\nIf you want to test the library, please visit the sample app on [Google Play](https://play.google.com/store/apps/details?id=com.chillibits.simplesettingssample)!\n\n## Screenshots (Android 11)\n\u003cimg src=\"https://github.com/marcauberer/simple-settings/raw/main/media/screenshots/screen1.png\" width=\"205\" title=\"Screenshot 1\"\u003e \u003cimg src=\"https://github.com/marcauberer/simple-settings/raw/main/media/screenshots/screen2.png\" width=\"205\" title=\"Screenshot 2\"\u003e \u003cimg src=\"https://github.com/marcauberer/simple-settings/raw/main/media/screenshots/screen3.png\" width=\"205\" title=\"Screenshot 3\"\u003e \u003cimg src=\"https://github.com/marcauberer/simple-settings/raw/main/media/screenshots/screen4.png\" width=\"205\" title=\"Screenshot 4\"\u003e\n\n## Usage\nThe first step for using this library is, to add it to the dependency section in your project:\n\nAdd repository to build.gradle file on project level:\n```gradle\nallprojects {\n    repositories {\n        ...\n        maven { url \"https://jitpack.io\" }\n    }\n}\n```\n\nAdd dependencies to build.gradle file on module level (e.g. app/build.gradle):\n```gradle\nimplementation 'com.chillibits:simplesettings:1.3.4'\n\n// Required dependencies\nimplementation 'com.google.android.material:material:\u003clatest-version\u003e'\nimplementation 'androidx.preference:preference-ktx:\u003clatest-version\u003e'\n```\n\nThe library accepts two different ways, for providing the settings screen information.\n\n### Provide items programmatically\nDepending on the complexity of your app, you can stick with a single-paged settings screen or you might choose a paged settings screen for more complex configurations.\n#### Single-Paged configuration\nYou can create the settings items, by using the `show()` method with the callback like this:\n```kotlin\nSimpleSettings(this).show {\n    Section {\n        title = \"Test section\"\n        for (i in 1..4) {\n            SwitchPref {\n                title = \"Test 1.$i\"\n                summary = \"This is a Test 1.$i\"\n                defaultValue = if(i % 2 == 0) SimpleSwitchPreference.ON else SimpleSwitchPreference.OFF\n            }\n        }\n        if(true) {\n            TextPref {\n                title = \"Test 2\"\n                summary = \"This is a Test 2\"\n            }\n        }\n        /*...*/\n    }\n    Section {\n        InputPref {\n            title = \"Test 3\"\n            summary = \"This is a Test 3\"\n        }\n        /*...*/\n    }\n    /*...*/\n}\n```\nThis is especially useful, when you need to generate your preferences at runtime. You can use loops and conditions as you can see above.\n\n*Note: If you want to pass a string / drawable / layout with its resource id, please use the properties with the `Res` suffix. For example:  `titleRes = R.string.app_name`.*\n\n*Note: It is not mandatory to pass keys to each preference. In this cases, the library does auto-generate a key by converting the title of each preference to CamelCase.*\u003cbr\u003e\n**Examples**:\n```\nList Preference --\u003e listPreference\nListPreference --\u003e listpreference\nThis is a custom preference --\u003e thisIsACustomPreference\ncustom --\u003e custom\n```\n\nYou can optionally pass an object of `SimpleSettingsConfig` to the constructor of your `SimpleSettings` instance, to customize the appearance of the settings activity. The different customization options are listed [below](#library-customization).\n\n#### Paged Settings Screens\nThe library offers a solution for overloaded single-paged settings screens by supporting paged settings configurations.\n```kotlin\nSimpleSettings(this).show {\n    Section {\n        title = \"Section\"\n        Page {\n            title = \"Page 1\"\n            summary = \"Demo summary 1\"\n            displayHomeAsUpEnabled = false\n            Section {\n                title = \"Demo subsection\"\n                TextPref {\n                    title = \"LibsClickListener\"\n                    onClick = LibsClickListener(this@MainActivity)\n                }\n                /*...*/\n            }\n        }\n        Page {\n            title = \"Page 2\"\n            summary = \"Demo summary 2\"\n            activityTitle = \"Page 2.2\"\n            Section {\n                DropDownPref {\n                    title = \"DropDownPreference\"\n                    simpleSummaryProvider = true\n                    entries = listOf(\"Apple\", \"Banana\", \"Avocado\", \"Pineapple\")\n                }\n                /*...*/\n            }\n        }\n        /*...*/\n    }\n    Section {\n        InputPref {\n            title = \"InputPreference\"\n            summary = \"Click to set text\"\n            defaultValue = \"Default text\"\n        }\n        /*...*/\n    }\n    /*...*/ \n}\n```\nTo learn more about the Page component, please visit its [wiki entry](https://github.com/marcauberer/simple-settings/wiki/PreferencePage).\n\n#### Page Headers\nThe library supports page headers and allows you to pass layout resources to every page of your settings screen.\nFor more information and code samples, please visit the [corresponding wiki entry](https://github.com/marcauberer/simple-settings/wiki/PreferenceHeader).\n\n### Provide items with xml file (only for single-paged configuration)\nYou also can specify your preference screen [as an usual xml file](https://developer.android.com/guide/topics/ui/settings#create_a_hierarchy):\n```xml\n\u003cPreferenceScreen\n    xmlns:app=\"http://schemas.android.com/apk/res-auto\"\u003e\n\n    \u003cPreferenceCategory\n        app:key=\"preference_category\"\n        app:title=\"Preference category\"\u003e\n\n        \u003cPreference\n            app:key=\"preference_test\"\n            app:title=\"Test\"\n            app:summary=\"This is a test preference\"/\u003e\n\n        \u003cSwitchPreferenceCompat\n            app:key=\"test\"\n            app:defaultValue=\"true\"\n            app:title=\"Test\"\n            app:summary=\"This is a test\"/\u003e\n            \n        \u003c!-- ... --\u003e\n    \u003c/PreferenceCategory\u003e\n    \u003c!-- ... --\u003e\n\u003c/PreferenceScreen\u003e\n```\n\nto build the settings screen in its default configuration, you can simply call the `show` method of SimpleSettings and pass the prepared xml resource file to it.\n\n```kotlin\nSimpleSettings(this@MainActivity).show(R.xml.preferences)\n```\n\nor (if you need to add PreferenceClickListeners to the preference items)\n\n```kotlin\nprivate fun showPreferences() {\n    val config = SimpleSettingsConfig().apply {\n        showResetOption = true\n        preferenceCallback = this@MainActivity\n    }\n    SimpleSettings(this@MainActivity, config).show(R.xml.preferences)\n}\n\noverride fun onPreferenceClick(context: Context, key: String): Preference.OnPreferenceClickListener? {\n    return when(key) {\n        \"preference\" -\u003e WebsiteClickListener(this@MainActivity, getString(R.string.url_github))\n        \"custom-preference\" -\u003e Preference.OnPreferenceClickListener {\n\n            true\n        }\n\n        else -\u003e super.onPreferenceClick(context, key)\n    }\n}\n```\n\n## Preference Types\n-   SimpleTextPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleTextPreference))\n-   SimpleSwitchPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleSwitchPreference))\n-   SimpleInputPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleInputPreference))\n-   SimpleListPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleListPreference))\n-   SimpleMultiSelectListPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleMSListPreference))\n-   SimpleCheckboxPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleCheckboxPreference))\n-   SimpleDropDownPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleDropDownPreference))\n-   SimpleSeekbarPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleSeekbarPreference))\n-   SimpleLibsPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleLibsPreference))\n-   SimpleColorPreference ([usage information](https://github.com/marcauberer/simple-settings/wiki/SimpleColorPreference))\n\n## Retrieve preference values\n### One-Time-Retrieval\nYou can either retrieve the values of the preferences as usual via the SharedPreferences or you can use the built-in shortcuts, coming with the library.\nIt provides extension functions for the `Context` class to easily access the preference values:\n```kotlin\nval value1 = getPrefStringValue(\"stringPreference\", \"default value\")\nval value2 = getPrefIntValue(\"intPreference\", 99)\nval value3 = getPrefBooleanValue(\"booleanPreference\", true)\nval value4 = getPrefFloatValue(\"floatPreference\", 101.6f)\nval value5 = getPrefLongValue(\"longPreference\", 4834597833234)\nval value6 = getPrefStringSetValue(\"stringSetPreference\", setOf(\"Default 1\", \"Default 2\"))\n```\nAs you can see, this works for the types `String`, `Int`, `Boolean`, `Float`, `Long`, `StringSet`.\n\n### Retrieval as LiveData\nFurthermore, the library offers a feature to observe preference values as LiveData as follows:\n```kotlin\nval inputPref = getPreferenceLiveData(this@MainActivity, \"listpreference\")\n```\n\nor you can retrieve it directly as an LiveData Observer:\n```kotlin\ngetPrefObserver(this@MainActivity, \"listpreference\", Observer\u003cString\u003e { value -\u003e\n    textField.text = value\n})\n```\n\nLike above, this works for the types `String`, `Int`, `Boolean`, `Float`, `Long`, `StringSet`.\u003cbr\u003e\n*Note: This extension functions are only available for the classes, which implement `LifecycleOwner`.*\n\n## Library customization\nThe library offers a few customization options. For applying those options, you have to pass an object of `SimpleSettingsConfig` to the constructor of your `SimpleSettings` instance.\n\n| Method                            | Description                                                                                                                                                                                            |\n|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `setActivityTitle(String)`        | Sets the toolbar title for the SettingsActivity. The default value is 'Settings', translated to all supported languages                                                                                |\n| `setActivityTitle(Context, Int)`  | Sets the toolbar title for the SettingsActivity with a string resource. The default value is 'Settings', translated to all supported languages                                                         |\n| `displayHomeAsUpEnabled(Boolean)` | Enables or disables the arrow icon in the top left corner of the activity to return to the calling activity. Default is `true`                                                                         |\n| `showResetOption(Boolean)`        | Enables or disables an options menu item for resetting all preferences to the default values. Default is `false`                                                                                       |\n| `setPreferenceCallback(Context)`  | Sets a callback for subscribing to click events of preference items                                                                                                                                    |\n| `setPendingTransition(Int, Int)`  | Specifies custom activity transition animations for closing the activity. More details [here](https://github.com/marcauberer/simple-settings/wiki/activity-configuration#custom-activity-transitions). |\n\nIf you miss a customization option, please let us know, by opening an issue.\n\n## Predefined click listeners\nThe library offers a few predefined click listeners to save you lots of boilerplate code. These click listeners are available:\n\n-   DialogClickListener ([more information](https://github.com/marcauberer/simple-settings/wiki/DialogClickListener))\n-   LibsClickListener ([more information](https://github.com/marcauberer/simple-settings/wiki/LibsClickListener))\n-   PlayStoreClickListener ([more information](https://github.com/marcauberer/simple-settings/wiki/PlayStoreClickListener))\n-   ToastClickListener ([more information](https://github.com/marcauberer/simple-settings/wiki/ToastClickListener))\n-   WebsiteClickListener ([more information](https://github.com/marcauberer/simple-settings/wiki/WebsiteClickListener))\n\n## Dive in deeper into the project\nPlease visit [the wiki](https://github.com/marcauberer/simple-settings/wiki), if you want to understand the perks of this library or if you want to learn more about certain preference types.\n\n## Supported languages\nHere are the currently supported languages for this library.\n\n-   English\n-   German\n-   French\n\nNew translations are highly appreciated. If you want to translate the lib, please open a pr.\n\n## Contribute to the project\nIf you want to contribute to this project, please feel free to send us a pull request.\n\n## Used third party libraries\n\n- [AboutLibraries by Mike Penz](https://github.com/mikepenz/AboutLibraries)\n- [FastAdapter by Mike Penz](https://github.com/mikepenz/FastAdapter)\n- [LivePreferences by İbrahim Süren](https://github.com/ibrahimsn98/live-preferences)\n- [ColorPickerPreference by Jaewoong Eum](https://github.com/skydoves/ColorPickerPreference)\n\n## Credits\nThanks to all contributors and translators!\n\n© Marc Auberer 2020-2022\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcauberer%2Fsimple-settings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcauberer%2Fsimple-settings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcauberer%2Fsimple-settings/lists"}