{"id":19166722,"url":"https://github.com/yarolegovich/materialpreferences","last_synced_at":"2025-04-13T02:10:09.584Z","repository":{"id":50276761,"uuid":"58946515","full_name":"yarolegovich/MaterialPreferences","owner":"yarolegovich","description":"A highly flexible set of lovely looking views that provides functionality of preferences.","archived":false,"fork":false,"pushed_at":"2020-08-01T11:02:14.000Z","size":2629,"stargazers_count":482,"open_issues_count":5,"forks_count":67,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-13T02:09:55.315Z","etag":null,"topics":["android","android-library","android-ui","material-design","material-ui","preferences","sharedpreferences"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yarolegovich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-16T16:04:07.000Z","updated_at":"2024-12-26T10:27:49.000Z","dependencies_parsed_at":"2022-08-25T14:11:55.207Z","dependency_job_id":null,"html_url":"https://github.com/yarolegovich/MaterialPreferences","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FMaterialPreferences","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FMaterialPreferences/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FMaterialPreferences/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FMaterialPreferences/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yarolegovich","download_url":"https://codeload.github.com/yarolegovich/MaterialPreferences/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654090,"owners_count":21140236,"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","android-library","android-ui","material-design","material-ui","preferences","sharedpreferences"],"created_at":"2024-11-09T09:34:06.242Z","updated_at":"2025-04-13T02:10:09.407Z","avatar_url":"https://github.com/yarolegovich.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaterialPreferences \n\nThis library is a set of VIEWS (not Preferences) and is aimed to solve this problems:\n* Preferences look ugly on pre-lollipop.\n* Preferences are not flexible. For example, it can be problematic to embed them to another screen (especially for fragment-haters).\n* Preferences don't allow you to show custom selection dialogs.\n\n![Screenshots](https://raw.githubusercontent.com/yarolegovich/materialpreferences/master/art/screenshots.png)\n\n## Gradle \nAdd this into your dependencies block:\n```\ncompile 'com.yarolegovich:mp:1.1.6'\n```\nFor [LovelyInput](#lovelyinput) you will also need this:\n```\ncompile 'com.yarolegovich:lovelyinput:1.1.6'\n```\nAnd jitpack to the list of repositories:\n```\nmaven { url \"https://jitpack.io\" }\n```\n\n## Wiki \nSample project that shows how to work with different library features is available as [sample module](https://github.com/yarolegovich/MaterialPreferences/tree/master/sample).\nYou can also [download APK](https://github.com/yarolegovich/MaterialPreferences/raw/master/sample/sample.apk) and play with it. \n\n### Contents\n\n1. [Types of preferences](#types-of-preferences)\n2. [UserInputModule](#userinputmodule)  \n  Allows you to show any dialogs (or event not dialogs) you want, when some preferencesare clicked.\n3. [StorageModule](#storagemodule)  \n  Allows you to save/retrieve values to/from any data source.\n4. [LovelyInput](#lovelyinput)  \n  Implementation of UserInputModule based on [LovelyDialog](https://github.com/yarolegovich/LovelyDialog) library.\n \n### Types of preferences\nThere are 2 ViewGroup classes: \n* [MaterialPreferenceScreen](#materialpreferencescreen)\n* [MaterialPreferenceCategory](#materialpreferencecategory)\n\nAnd a lot of AbsMaterialPreference subclasses:\n* [MaterialStandardPreference](#materialstandardpreference)\n* [MaterialRightIconPreference](#materialrighticonpreference)\n* [AbsMaterialTextValuePreference](#absmaterialtextvaluepreference)\n * [AbsMaterialListPreference](#absmateriallistpreference)\n    * [MaterialChoicePreference](#materialchoicepreference)\n    * [MaterialMultiChoicePreference](#materialmultichoicepreference)\n * [MaterialEditTextPreference](#materialedittextpreference)\n* [AbsMaterialCheckablePreference](#absmaterialcheckablepreference)\n * [MaterialSwitchPreference](#materialswitchpreference)\n * [MaterialCheckboxPreference](#materialcheckboxpreference)\n* [MaterialColorPreference](#materialcolorpreference)\n* [MaterialSeekBarPreference](#materialseekbarpreference) \n \nEach preference contains optional title, summary and icon (icon can be tinted). Also for some preferences\nit is mandatory to set default value and key (at least when dealing with SharedPreference as [StorageModule](#storagemodule)).\n```xml\n\u003ccom.yarolegovich.mp.AnyAbsMaterialPreferenceSubclass\n    xmlns:app=\"http://schemas.android.com/apk/res-auto\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    app:mp_icon=\"@drawable/your_icon\"\n    app:mp_icon_tint=\"@color/textSecondary\"\n    app:mp_title=\"@string/your_title\"\n    app:mp_summary=\"@string/your_summary\"\n    app:mp_key=\"@string/pkey_your_key\"\n    app:mp_default_value=\"42|true|any string\"/\u003e\n```\n\n#### MaterialPreferenceScreen\nViewGroup.In essence - scrollable LinearLayout. Use it or not is a matter of preference, but it has some useful features.\n```java\npublic void setVisibilityController(int controllerId, List\u003cInteger\u003e controlledIds, boolean showWhenChecked);\npublic void setVisibilityController(final AbsMaterialCheckablePreference controller, final List\u003cInteger\u003e controlledIds, final boolean showWhenChecked);\n```\nSets some checkable preference to control visibility of views with specified ids. Last parameter is used to define when views should be visible (if preference is checked or not).\n```java\nMaterialPreferenceScreen screen = (MaterialPreferenceScreen) findViewById(R.id.preference_screen);\nscreen.setVisibilityController(R.id.pref_auto_loc, Arrays.asList(R.id.pref_location), false);\n```\nNow when our R.id.pref_auto_loc preference is checked/unchecked - R.id.pref_location will be hidden/shown. \n\n#### MaterialPreferenceCategory\nViewGroup. Has optional attributes\n```xml\napp:mpc_title=\"@string/your_title\"\napp:mpc_title_color=\"@color/your_color\"\n```\nto specify a title and title color for category. In essence - CardView with vertical LinearLayout inside it. \n\n#### MaterialStandardPreference\nThe simplest preference. Doesn't perform anything (until you set OnClickListener on it). Saves nothing.\n\n#### MaterialRightIconPreference\nThe same as MaterialStandardPreference, but icon is on the right. Saves nothing.\n\n#### AbsMaterialTextValuePreference\nSometimes I want to show current value of preference in summary or maybe on the right of the row. With sublcasses of \nMaterialTextInputPreference you have an option to do this by using: \n```xml\n\u003c!-- default is notShow --\u003e \napp:mp_show_value=\"notShow|onBottom|onRight\" \n```\nattribute. It can take one of the listed values, that I think are pretty self-explanatory. Any subclass has access to this functionality.\n\n#### AbsMaterialListPreference\nSubclass of [AbsMaterialTextValuePreference](#absmaterialtextvaluepreference). Defines two attributes:\n```xml\napp:mp_entry_descriptions=\"@array/some_string_array\"\napp:mp_entry_values=\"@array/some_string_array\"\n```\nThe first one contains values that will be shown in the dialog when preference is clicked. Second contains values that will be saved\nafter some item is selected. If one attribute is omitted - another one will be used for both purposes.\n\n#### MaterialChoicePreference\nSubclass of [AbsMaterialListPreference](#absmateriallistpreference). On click shows dialog with items from mp_entry_descriptions,\nwhen any item is selected - item with corresponding index from mp_entry_values will be saved. Saves String value.\n\n#### MaterialMultiChoicePreference\nSubclass of [AbsMaterialListPreference](#absmateriallistpreference). On click shows dialog with items from mp_entry_descriptions, \nany number of items can be checked and after the dialog is dismissed - items from mp_entry_values with indices that correspond to \nindices of checked items will be saved. Saves Set\u003cString\u003e value.\nClass also defines attribute:\n```xml \napp:mp_default_selected=\"@array/checked_items\"\n```\nTo specify items selected by default.\n\n#### MaterialEditTextPreference\nSubclass of [AbsMaterialTextValuePreference](#absmaterialtextvaluepreference). On click shows dialog with EditText and confirm button. \nAfter confirm button is clicked - text will be saved. Saves String value.\n\n#### AbsMaterialCheckablePreference\nContains some checkable view and changes its state on click. All subclasses save boolean.\n\n#### MaterialSwitchPreference\nSubclass of [AbsMaterialCheckablePreference](#absmaterialcheckablepreference). Contains SwitchCompat view on the right.\n\n#### MaterialCheckboxPreference\nSubclass of [AbsMaterialCheckablePreference](#absmaterialtextvaluepreference). Contains CheckBox view on the right. \n\n#### MaterialColorPreference\nContains custom ColorView on the right that reflects currently selected color. Defines attributes:\n```xml \napp:mp_initial_color=\"@color/your_color\"\napp:mp_border_color=\"@color/your_color\"\napp:mp_border_width=\"@dimen/your_width\"\napp:mp_indicator_shape=\"circle|square\"\n```\nOn click shows color picker dialog. By default it uses [VintageChroma](https://github.com/MrBIMC/VintageChroma). Saves color int.\n\n#### MaterialSeekBarPreference\nContains AppCompatSeekBar view under the summary and optional TextView that reflects current value. Defines attributes:\n\n```xml \napp:mp_max_val=\"12\"\napp:mp_min_val=\"1\"\napp:mp_show_val=\"true\"\n```\nTextView with current value will be shown if mp_show_val is set to true (which is not by default). Saves int.\n\n### UserInputModule\n\nInterface that defines methods called when some preferences are clicked:\n* MaterialEditTextPreference -\u003e showEditTextInput(...)\n* MaterialChoicePreference -\u003e showSingleChoiceInput(...)\n* MaterialMutltiChoicePreference -\u003e showMultiChoiceInput(...)\n* MaterialColorPreference -\u003e showColorSelectionInput(...)\n\nIf you want some special look of your dialogs you need to implement this interface together with UserInputModule.Factory.\nThen you need to set it as default UserInputModule or as UserInputModule for specific screen.\n\nTo see real example refer to [this project](https://github.com/yarolegovich/MaterialPreferences/tree/master/lovelyinput).\n\nSuppose you have classes:\n```java\npublic class MyFancyInputModule implements UserInputModule { ... }\n\npublic class MyFancyInputModuleFactory implements UserInputModule.Factory { ... }\n```\nThen you need to do the following to set it as a default module:\n```java \nMaterialPreferences.instance().setUserInputModule(new MyFancyInputModuleFactory());\n```\nOr set is as module for some specific screen:\n```java\nMaterialPreferencScreen screen = (MaterialPreferenceScreen) findViewById(R.id.preference_screen);\nscreen.setUserInputModule(new MyFancyInputModuleFactory());\n```\n\n### StorageModule\n\nInterface that defines methods called by preferences to save/retrieve value. This gives you additional flexibility, because preferences\nnow can be used for different purposes - you can even [initialize POJOs](https://github.com/yarolegovich/MaterialPreferences/blob/master/sample/src/main/java/com/yarolegovich/materialprefsample/FormInitializer.java) with the help of this feature.\n\nTo set your storage module follow the same procedure as with UserInputModule.\n\nSuppose you have classes:\n```java\npublic class MyCoolStorageModule implements StorageModule { ... }\n\npublic class MyCoolStorageModuleFactory implements StorageModule.Factory { ... }\n```\nThen you need to do the following to set it as a default module:\n```java \nMaterialPreferences.instance().setStorageModule(new MyCoolStorageModuleFactory());\n```\nOr set is as module for some specific screen:\n```java\nMaterialPreferencScreen screen = (MaterialPreferenceScreen) findViewById(R.id.preference_screen);\nscreen.setStorageModule(new MyCoolStorageModuleFactory());\n```\nIf you want to store data inside preferences, but not default - you can use:\n```java\nnew SharedPrefsStorageFactory(\"filename\")\n```\n\n### LovelyInput\nImplementation of [UserInputModule](#userinputmodule) combined with my another library - [LovelyDialog](https://github.com/yarolegovich/LovelyDialog). \nFor information on how to use it - [check sample](https://github.com/yarolegovich/MaterialPreferences/blob/master/sample/src/main/java/com/yarolegovich/materialprefsample/MainActivity.java#L63).\nYou can use not only \n```java\nsetKeyIconMappings(Set\u003cString, Integer\u003e mappings);\n```\nbut also \n```java\nsetKeyTitleMappings(Set\u003cString, String\u003e mappings);\nsetKeyMessageMappings(Set\u003cString, String\u003e mappings);\n```\n[Source code](https://github.com/yarolegovich/MaterialPreferences/tree/master/lovelyinput/src/main/java/com/yarolegovich/lovelyuserinput) of module can serve you as an example of custom UserInputModule. \n\n### License\n```\nCopyright 2016 Yaroslav Shevchuk\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyarolegovich%2Fmaterialpreferences","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyarolegovich%2Fmaterialpreferences","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyarolegovich%2Fmaterialpreferences/lists"}