{"id":19847054,"url":"https://github.com/polidea/cockpit","last_synced_at":"2026-03-05T19:07:09.549Z","repository":{"id":77350955,"uuid":"128928904","full_name":"Polidea/Cockpit","owner":"Polidea","description":"Easily define a set of parameters that can be accessed and changed by the developers via built-in compact UI at runtime.","archived":false,"fork":false,"pushed_at":"2020-02-21T15:28:42.000Z","size":34931,"stargazers_count":120,"open_issues_count":2,"forks_count":9,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-03-20T02:20:25.896Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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/Polidea.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,"governance":null}},"created_at":"2018-04-10T12:26:41.000Z","updated_at":"2024-02-22T01:23:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"1df432ae-9c44-4680-a7c8-5521df2da1a7","html_url":"https://github.com/Polidea/Cockpit","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polidea%2FCockpit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polidea%2FCockpit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polidea%2FCockpit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polidea%2FCockpit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Polidea","download_url":"https://codeload.github.com/Polidea/Cockpit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224278377,"owners_count":17285080,"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":[],"created_at":"2024-11-12T13:13:17.927Z","updated_at":"2026-03-05T19:07:09.473Z","avatar_url":"https://github.com/Polidea.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cockpit\n\u003cp align=\"center\"\u003e\n  \u003cimg\n    alt=\"Cockpit library logo\"\n    src=\"images/cockpit-logo.png\"\n    height=\"300\"\n    style=\"margin-top: 20px; margin-bottom: 20px;\"\n  /\u003e\n\u003c/p\u003e\n\n## Introduction\n\nCockpit is a helpful tool – a debug menu – for Android developers, testers and designers providing a way to define a set of params that can be used in the application and changed anytime without having to recompile the project. It also provides a compact built-in UI so using the library is as simple as possible.\n\nIt consists of three parts:  \n- Gradle plugin generating a set of params based on user-defined yaml file,  \n- Android library containing classes to manage and display those params,  \n- CockpitCore module containing classes common for plugin and the library.\n\n\u003cimg src=\"https://github.com/Polidea/Cockpit/blob/a5d9b822b7bccbebf1800a5cc9a25f67429a7a92/images/cockpit-3.1.0.gif\" width=\"270\" height=\"480\"\u003e\n\nEach defined value is called `param`. The set of params is called `cockpit`.\n\n## Usage\nIn [Getting started](#getting-started) we show the most basic example of how to get Cockpit to work in your project. If you're interested in more, please take a look at [Documentation](#documentation) section below.\n\n### Getting started\nTo start, you need to integrate Cockpit into your app. Please take a look at [Installation](#installation) section to learn how to do it. When you're all set up, create **cockpit.yml** file and put it in your application's **your_app_module_name/cockpit** folder. It can look like this:\n```\ncolor:\n  type: color\n  description: \"Text color\"\n  value: \"#00ff33\"\ncolorDescription: \"Calm green\"\nfontSize: 30\nshowDescription: true\n```\nAfter you've built your project, `Cockpit.java` file will get generated for you. You can use it like any other code in your project.\n\n\u003cp float=\"left\"\u003e\n    \u003cimg src=\"https://github.com/Polidea/Cockpit/blob/a5d9b822b7bccbebf1800a5cc9a25f67429a7a92/images/cockpit-full.png\" width=\"216\" height=\"384\" /\u003e\n    \u003cimg src=\"https://github.com/Polidea/Cockpit/blob/a5d9b822b7bccbebf1800a5cc9a25f67429a7a92/images/cockpit-half.png\" width=\"216\" height=\"384\" /\u003e\n    \u003cimg src=\"https://github.com/Polidea/Cockpit/blob/a5d9b822b7bccbebf1800a5cc9a25f67429a7a92/images/cockpit-list.png\" width=\"216\" height=\"384\" /\u003e\n\u003c/p\u003e\n\n### Documentation\n\nBelow, divided into sections, you can find a detailed description on how to use Cockpit and its features.\n#### Defining params\nTo define cockpit, you need to create **cockpit.yml** file and place it in your application's **your_app_module_name/cockpit** folder. Params defined in **cockpit.yml** are applied to all flavors. In order to extend or change cockpit depending on the flavor, create additional files using following naming convention:\ncockpit\u003cflavor_name\u003e.yml where `\u003cflavorName\u003e` is a desired flavor.\n\nExamples:\n```\ncockpitDebug.yml\ncockpitStaging.yml\ncockpitStagingDebug.yml\n```\n\nFor basic functionality you can use simple, flat yaml structure, for example:\n```\ntext: \"example\"\nendpointList: [ \"staging\", \"testing\", \"prod\" ]\nfontSize: 18\nshowDialog: true\n```\n\nIf you need some more attributes or want to use action param, you can use more complex structure. Currently Cockpit debug panel supports following param types:\n##### primitives (integer, double, string, boolean)\n\n```\nfontSize:\n  description: \"Header font size\" # this field is optional; if provided, it's used for display instead of param name\n  value: 18\n```\n\n##### action\n```\nshowDialog:\n  type: action\n  description: \"Show dialog\" # optional\n  buttonText: \"Perform\" # this value is optional\n```\n\n##### list\n```\nendpointList:\n  type: list\n  values: [ \"staging\", \"testing\", \"prod\" ]\n  selectedItemIndex: 1 # this field is optional; if not provided, 0 is assumed\n```\n\n##### range slider\n```\nlengthSlider:\n  type: range\n  min: 0\n  max: 32\n  value: 8 # optional; if not provided, min is assumed\n  step: 0.1 # optional; if not provided, 1 is assumed\n  description: \"Length\" # optional\n```\n\n##### step\n```\nfontSize:\n  type: step\n  value: 36\n  step: 2\n  min: 20 # optional\n  max: 60 # optional\n  description: \"Total price font size\" # optional\n```\n\n##### color\n```\nfontColor:\n  type: color\n  description: \"Font color\" # optional\n  value: \"#223344\" # supported color formats are #AARRGGBB and #RRGGBB\n```\n\n##### read only param\n```\nappVersion:\n  type: read_only\n  description: \"Version\" # optional\n```\n\n`read_only` param can be used when you have some information you want to display in Cockpit panel, but you don't need to change it. Build version is a good example. To set value of such param, you'll need to use generated setter for that param before displaying Cockpit panel. Value will be displayed in a TextView.\n\n\u003e Supported param types are integer, double, string, boolean, list, color, step, range and action. All items inside a list have to be the same type.\n\n\u003e Please note that param names are case-sensitive and have to be unique.\n\n\u003e You can create **groups of params** and name them. To define a group, you need to use extended structure of a param and add \"group\" field. All parameters without defined groups will be listed as part of \"Default\" group.\n```\nfontSize:\n  description: \"Font size\"\n  value: 18\n  group: \"Header\"\nfontColor:\n  type: color\n  description: \"Font color\"\n  value: \"#223344\"\n  group: \"Header\"\n```\n\n\u003e You can create **paged subgroups** as well. To define a paged subgroup, use slashes in group name. If you begin your subgroup's name with `/`, it will be placed inside `Default` group. You can embed the subgroups as deep as you see fit. To navigate between the subgroups, use home button on the action bar or `NAVIGATE TO` button.\n\nThe following snippet will create group named `Display` with subgroup `Header` and parameters `fontSize` and `fontColor` inside.\n```\nfontSize:\n  description: \"Font size\"\n  value: 18\n  group: \"Display/Header\"\nfontColor:\n  type: color\n  description: \"Font color\"\n  value: \"#223344\"\n  group: \"Display/Header\"\n```\n\n#### Generating Cockpit\n\nCockpitPlugin will generate `Cockpit.java` file for you.\nCockpit functionality is by design available only in debug builds, so `Cockpit.java` file in the release build will contain:\n- only getters for primitive param types,\n- selected value getter for list type,\n- nothing for action type.\n\nThis is to prevent any unauthorized param value changes.\n\n#### Accessing param values\nYou can access the params via generated getters and setters. Each primitive type param has corresponding `getParamName()` and `setParamName()`, where `paramName` is your param's name. List param has `getParamNameSelectedValue()`.\n\n#### Listening for value changes\nYou can listen for value changes by adding appropriate PropertyChangeListeners.\\\nEach changeable param has methods `addOnParamNameChangeListener()` and `removeOnParamNameChangeListener()`, where `paramName` is param's name.\n\n#### Listening for action requests\nAction params don't change their values. They request performing an action every time you click on the corresponding button.\nTo listen for those requests action param has `addParamNameActionRequestCallback()` and `removeParamNameActionRequestCallback()` methods, where `paramName` is param's name.\n\n#### Displaying Cockpit\nCockpit library offers an easy way to display and edit all the params you defined. All you need to do is call\n`Cockpit.showCockpit(fragmentManager: FragmentManager)`\nThis will display our compact, built-in developer menu UI where you can edit the params' values. When you're done, just dismiss the dialog.\n\nTo make it easy to observe your changes, you can collapse or expand Cockpit dialog, resize it or drag it all over the screen.\n\n#### Restoring default values\nAfter you've made some changes in Cockpit and decided you didn't like them, it's helpful to be able to restore default values. You can do it globally or for selected param only using curved arrow icon.\n\n## Installation\nTo integrate Cockpit debug menu into your project, you'll need to add several pieces of code to your `build.gradle`.\n\nFirst, add plugin declaration:\n```\napply plugin: 'com.polidea.cockpit'\n```\n\nAdd `mavenCentral()` and `maven` into your `buildscript#repositories` section. Also add `jitpack` as Cockpit uses ColorPicker version available only there:\n```\nbuildscript {  \n    repositories {\n        mavenCentral()  \n        maven {  \n            url \"https://plugins.gradle.org/m2/\"\n        }\n    }\n}\n\nallprojects {\n    repositories {\n        maven { \n            url \"https://jitpack.io\" \n        }\n    }\n}\n\n```\n\nThen add CockpitPlugin classpath into your `buildscript#dependencies`:\n\n```\nbuildscript {  \n    dependencies {  \n        classpath \"gradle.plugin.com.polidea.cockpit:CockpitPlugin:3.1.2\"\n   }  \n}\n```\nLast thing is to add Cockpit library dependency:\n\n```\ndependencies {\n    debugImplementation 'com.polidea.cockpit:cockpit:3.1.2'\n}\n```\n\n## Building sample app\nWhen you attempt to build the sample project for the first time, you're most likely to encounter `plugin not found` error. That's because sample app uses local build of the plugin. To fix the problem:\n- on MacOS/Linux run `./pluginAndCore.sh -b` from your project and then build sample app,\n- on Windows build CockpitCore, CockpitPlugin and, at last, sample app.\n\n## Integration ideas\nWhen it comes to library integration with your app, it really depends on what is available in your particular case. We think it's a nice idea to use Seismic library by Square (https://github.com/square/seismic) and launch Cockpit panel on shake:\n```kotlin\nclass SampleActivity: AppCompatActivity(), ShakeDetector.Listener {  \n\n    private val shakeDetector = ShakeDetector(this)  \n\n    override fun onCreate(savedInstanceState: Bundle?) {\n        super.onCreate(savedInstanceState)\n        setContentView(R.layout.activity_sample)\n\n        initShakeDetection()\n    }  \n\n    private fun initShakeDetection() {\n        val sensorManager = getSystemService(Context.SENSOR_SERVICE) as SensorManager\n        shakeDetector.start(sensorManager)\n    }  \n\n    override fun onStop() {\n        super.onStop()\n        shakeDetector.stop()\n    }\n\n    override fun hearShake() {\n        Cockpit.showCockpit(supportFragmentManager)\n    }\n}\n```\n\nAnother simple idea is to launch Cockpit debug panel on button click or on specific gesture (multi-touch, double tap, etc.).\n\nNo matter which way you choose, to display Cockpit, you just have to call `Cockpit#showCockpit(FragmentManager fragmentManager)` method.\n## Troubleshooting\nYou may come across following error:\n```\norg.gradle.api.tasks.StopExecutionException: Configuration on demand is not supported by the current version of the Android Gradle plugin since you are using Gradle version 4.6 or above.\nSuggestion: disable configuration on demand by setting org.gradle.configureondemand=false in your gradle.properties file or use a Gradle version less than 4.6.\n```\n\nTo get it to work, you need to disable configuration on demand in your Android Studio's settings (`Build, Execution, Deployment` -\u003e `Compiler`, uncheck `configure on demand` option).\n\n## Maintained by\nThis library is maintained by [Polidea](http://www.polidea.com)\n\n[Contact us](https://www.polidea.com/project/?utm_source=Github\u0026utm_medium=Npaid\u0026utm_campaign=Kontakt\u0026utm_term=Code\u0026utm_content=GH_NOP_KKT_COD_CPT001)\n\n## License\n```\nCopyright 2018-2019 Polidea\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\n    http://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%2Fpolidea%2Fcockpit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolidea%2Fcockpit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolidea%2Fcockpit/lists"}