{"id":13941806,"url":"https://github.com/bit101/quicksettings","last_synced_at":"2025-12-26T21:42:04.810Z","repository":{"id":40533471,"uuid":"44434241","full_name":"bit101/quicksettings","owner":"bit101","description":"JavaScript library for making a quick settings panel to control code parameters.","archived":false,"fork":false,"pushed_at":"2020-11-24T00:38:18.000Z","size":1608,"stargazers_count":458,"open_issues_count":16,"forks_count":52,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-11-27T11:37:10.287Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/bit101.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":"2015-10-17T11:15:38.000Z","updated_at":"2024-09-28T12:47:44.000Z","dependencies_parsed_at":"2022-06-30T01:34:03.457Z","dependency_job_id":null,"html_url":"https://github.com/bit101/quicksettings","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/bit101/quicksettings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bit101%2Fquicksettings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bit101%2Fquicksettings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bit101%2Fquicksettings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bit101%2Fquicksettings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bit101","download_url":"https://codeload.github.com/bit101/quicksettings/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bit101%2Fquicksettings/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266071519,"owners_count":23871940,"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-08-08T02:01:29.690Z","updated_at":"2025-07-20T05:31:10.279Z","avatar_url":"https://github.com/bit101.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","GUI Parameters \u0026 Settings"],"sub_categories":[],"readme":"# quicksettings\nQuickSettings is a JavaScript library for making a quick settings panel to control code parameters.\n\n**Note** - this project is not under active development. I may occasionally look at a PR and approve it if it is fairly clear, but I probably will not have time to dig into or respond to any issues.\n\n\n![QuickSettings Panel](images/master_demo.png)\n\n## Version 3 changes:\n\nVersion 3 is mostly about simplifying the panel, removing little used features and making getting and setting values easier.\n\n- New features / changes:\n    - All controls with settable values are now set with `panel.setValue(title, value)`\n    - All controls with gettable values are now read with `panel.getValue(title)`\n    - You can programatically get and set control values with JSON using `panel.getValuesAsJSON` and `panel.setValuesFromJSON`.\n    - Calling `saveInLocalStorage(name)` will cause all changes in the panel to be continuously synced to local storage and restored when the panel is restarted. See details below, and demo project.\n\n- Removed:\n    - `panel.addInfo` and related methods are gone. These were just aliased to `panel.addHTML` anyway, so use that instead.\n    - The functionality to parse an entire panel layout from JSON has been removed. This might be added in later as a separate module.\n    - The snap-to-grid functionality has been removed.\n    \nNaturally, many of these changes will break backwards compatibility with version 2 or earlier. But the changes overall result in a cleaner, simpler API and are easy enough to migrate over to.\n\n## Documentation and Demos\n\nSee http://bit101.github.com/quicksettings\n\n## Setup\n\nYou can use the files from this repo in your project or directly link to the main minified js file at:\n\n- https://cdn.jsdelivr.net/npm/quicksettings@latest/quicksettings.min.js\n\nIf you want to use a specific version, use the actual version number, such as \"2.0\" in place of \"latest\" in the url.\n\nQuickSettings is fully require.js compatible. So add the script to your HTML or use require to import it.\n\nWhen you create your first panel, QuickSettings will automatically inject its own default style sheet into the page. If you want to use a different style, call `QuickSettings.useExtStyleSheet()` prior to creating a panel. This will prevent the automatic css injection. You can then use one of the style sheets included in this repo or alter them to create your own styles.\n\nSee the Styles Demo for examples of all the styles:  http://bit101.github.io/quicksettings/demos/styles_demo.html (source: http://bit101.github.io/quicksettings/demos/styles.js)\n\n## Creating a Panel\n\nHTML UI controls are created within a QuickSettings panel on your page. Create the panel with:\n\n``` js\nvar settings = QuickSettings.create(x, y, panelTitle, parent);\n```\n    \nThe `x` and `y` parameters control the initial position of the panel and default to 0, 0.\n\nThe `panelTitle` parameter lets you add an optional title. It defaults to the string, \"QuickSettings\".\n\nThe `parent` parameter lets you specify where on the DOM you want to add the panel and will default to the document's body element.\n    \nDestroying a panel removes it from the page and nulls out all methods and properties.\n\n``` js\nsettings.destroy();\n```\n\n## Adding Controls\n\nNow you can add controls to the panel. Supported controls are:\n\n``` js\nsettings.addBoolean(title, value, callback);                // creates a checkbox\nsettings.addButton(title, callback);                        // creates a button\nsettings.addColor(title, color, callback);                  // creates a color input\nsettings.addDate(title, date, callback);                    // adds a date input\nsettings.addDropDown(title, [items], callback);             // creates a dropdown list\nsettings.addElement(title, htmlELement);                    // adds any arbitrary HTML element to the panel\nsettings.addFileChooser(title, labelStr, filter, callback); // adds a file chooser\nsettings.addHTML(title, htmlString);                        // adds any arbitrary HTML to the panel\nsettings.addImage(title, imageURL, callback);               // creates and image element with the specified URL\nsettings.addNumber(title, min, max, value, step, callback); // creates a number input\nsettings.addPassword(title, text, callback);                // adds a password text field\nsettings.addProgressBar(title, max, value, valueDisplay);   // creates a progress bar\nsettings.addRange(title, min, max, value, step, callback);  // creates a range slider\nsettings.addText(title, text, callback);                    // creates an input text field\nsettings.addTextArea(title, text, callback);                // creates a resizable text area\nsettings.addTime(title, time, callback);                    // adds a time input\n  ```\n    \nSee Master Demo for all of these examples: http://bit101.github.io/quicksettings/demos/master_demo.html (source:  http://bit101.github.io/quicksettings/demos/masterdemo.js)\n    \nFor most controls, the callback will get passed the current value of the control. For the button, it passes a reference to the button itself. For the dropdown, it passes an object that contains properties index, label and value (the selected index and the label and value of the selected item). For the file chooser, it gets passed a File object represending the file that was chosen. The `addImage` callback is called when the image finished loading.\n\nThe color control implementation will vary on platforms. On some platforms, this will be the same as a text input. Color input is any valid color string such as \"#f00\", \"#ff0000\", \"red\", \"rgb(255, 0, 0)\", \"rgba(255, 0, 0, 1)\".\n\nThe date control implementation will vary on platforms. On some platforms, this will be the same as a text input. Date input must be in the form aof a string: \"YYYY-MM-DD\". Output value will be the same.\n\nThe time control implementation will vary on platforms. On some platforms, this will be the same as a text input. Time input must be in the form aof a string: \"HH-MM\" or \"HH:MM:SS\" in 24-hour format. Output value will be the same.\n\n## Querying Controls\n\nYou can also query the value of controls at any time with:\n\n``` js\nsettings.getValue(title);\n```\n\nIt's also possible to get an object containing all of the value for all user-interactive controls.\n\n``` js\nsettings.getValuesAsJSON(asString);\n```\n\nThis will give you an object containing the title and value of each object that can be changed by a user. Passing `true` for the `asString` parameter will give you a JSON-formatted string instead of an object.\n\nFor the file chooser, the Object version will include the actual File object representing the chosen file. The string version will stringify this to an empty object though: `\"{}\"`.\n\n## Setting Values Programatically    \n\nAnd set values of controls with:\n\n``` js\nsettings.setValue(title, value);\n```\n\nIf, for some reason, you need to change the min, max or step of a range input or number input, use:\n\n``` js\nsettings.setRangeParameters(title, min, max, step);\nsettings.setNumberParameters(title, min, max, step);\n```\n    \nSet the number of rows in a text area (defaults to 5) with:\n\n``` js\nsettings.setTextAreasRows(title, rows);\n```\n\nYou can also use the JSON you got by calling `getValuesAsJSON` in the method:\n\n``` js\nsettings.setValuesFromJSON(json);\n```\n\nThis will set all any controls named in the JSON with the values defined there. The Reset Demo has an example of using these methods to reset a panel to default values: http://bit101.github.io/quicksettings/demos/resetdemo.html (source: http://bit101.github.io/quicksettings/demos/resetdemo.js) \n\n## Persisting Controls with localStorage\n\nOnce you've set up your panel, you can call:\n\n``` js\nsettings.saveInLocalStorage(name);\n```\n\npassing in a unique string to store the panel settings. Doing so causes a few things to happen. First, QuickSettings will immediatedly check to see if settings have been previously saved under this name. If so, they will be loaded and applied to the existing panel, overwriting any values that were just set in the code. After that, whenever any changes are made to any controls in the panel, the current state of the panel will be saved in localStorage. The ideal place to call this method is after you have added and set up all other controls in the panel.\n\nSee the Local Storage Demo to view this in action: http://bit101.github.io/quicksettings/demos/localstoragedemo.html (source: http://bit101.github.io/quicksettings/demos/localstoragedemo.js)\n    \n## Managing Controls\n\nYou can remove any control with:\n\n``` js\nsettings.removeControl(title);\n```\n    \nOr disable and reenable any controls that can be enabled/disabled with:\n\n``` js\nsettings.disableControl(title);\nsettings.enableControl(title);\n```\n    \nOr hide and show any control:\n\n``` js\nsettings.hideControl(title);\nsettings.showControl(title);\n```\n    \nFinally, you can override most existing style properties for controls with:\n\n``` js\nsettings.overrideStyle(title, styleName, value);\n```\n\nFor example, to change the font size in an intput text field named \"text\":\n\n``` js\nsettings.overrideStyle(\"text\", \"fontSize\", \"20px\");\n```\n    \nMost controls, except for the boolean (checkbox) and button controls show a title label above the actual control. You can turn this on and off for any specific control:\n\n``` js\nsettings.hideTitle(title);\nsettings.showTitle(title);\n```\n    \nOr for all of the controls at once:\n\n``` js\nsettings.hideAllTitles();\nsettings.showAllTitles();\n```\n\n## Panel Settings\n\nThe panel is draggable and collapsible/expandable by a double click on the title bar by default. The following methods affect this behavior:\n\n``` js\nsettings.setDraggable(bool);\nsettings.setCollapsible(bool);\nsettings.collapse();\nsettings.expand();\nsettings.toggleCollapsed():\n```\n\nYou can show and hide the panel with the following:\n\n``` js\nsettings.show();\nsettings.hide();\nsettings.toggleVisibility();\n```\n  \nOr, you can set a keyboard key that will show and hide the panel when pressed:\n\n``` js\nsettings.setKey(char);\n```\n  \nYou can set the position of the panel with:\n\n``` js\nsettings.setPosition(x, y);\n```\n    \nBy default, the panel will be 200px wide and grow in height to fit its content. You can set an explicit size with:\n\n``` js\nsettings.setSize(w, h);\n```\n\nOr, perhaps more useful, you can set only the width and let the height continue to grow as normal:\n\n``` js\nsettings.setWidth(w);\n```\n\nYou can also set a fixed height. If the controls do not fit in this height, they will scroll.\n\n``` js\nsettings.setHeight(h);\n```\n\n## Responding to changes\n\nIn addition to adding a callback on each control, you can add a global change handler:\n\n``` js\nsettings.setGlobalChangeHandler(callback);\n```\n    \nThis callback will be called whenever any change is made to any control in this panel.\n\nThere are also bind functions:\n\n``` js\nsettings.bindBoolean(title, value, object);\nsettings.bindColor(title, color, object);\nsettings.bindDate(title, date, object);\nsettings.bindDropDown(title, [items], object);\nsettings.bindNumber(title, min, max, value, step, object);\nsettings.bindPassword(title, text, object);\nsettings.bindRange(title, min, max, value, step, object);\nsettings.bindText(title, text, object);\nsettings.bindTextArea(title, text, object);\nsettings.bindTime(title, time, object);\n```\n    \nThese function the same as their \"add\" counterparts, but instead of a callback, you pass in an object. When the control's value is changed, it will assign the new value to the property of that object that matches the title. For example:\n\n``` js\nsettings.bindBoolean(\"visible\", true, model);\n```\n    \nWhen the checkbox is clicked, it will set `model.visible` to true or false.\n\nThese two changes allow you to have a single model object and a single change handler, which can greatly simplify your code. See the Bind Demo: http://bit101.github.io/quicksettings/demos/binddemo.html (source: http://bit101.github.io/quicksettings/demos/binddemo.js).  \n\nNote that there are no bind functions for button, and several other controls that do not have changing values. The global change handler will be called when a button is pressed though.\n\n## Misc.\n\nPretty much every method that is not a getter will return a reference to the panel itself, allowing you to chain calls.\n\n``` js\nvar panel = QuickSettings.create(10, 10, \"Panel\")\n    .addRange(\"x\", 0, 100, 50, 1)\n    .addRange(\"y\", 0, 100, 50, 1)\n    .addRange(\"w\", 0, 100, 50, 1)\n    .addRange(\"h\", 0, 100, 50, 1)\n    .setGlobalChangeHandler(myChangeHandler);\n```\n        \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbit101%2Fquicksettings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbit101%2Fquicksettings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbit101%2Fquicksettings/lists"}