{"id":24236891,"url":"https://github.com/cmdwtf/imgui_toggle","last_synced_at":"2025-04-13T02:10:38.669Z","repository":{"id":62891189,"uuid":"563385072","full_name":"cmdwtf/imgui_toggle","owner":"cmdwtf","description":"A toggle switch widget for Dear ImGui","archived":false,"fork":false,"pushed_at":"2025-01-07T17:25:12.000Z","size":3984,"stargazers_count":222,"open_issues_count":4,"forks_count":25,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-04T04:36:28.758Z","etag":null,"topics":["cplusplus","dear-imgui","gui","imgui","widgets"],"latest_commit_sha":null,"homepage":"https://cmd.wtf/projects#imgui-toggle","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmdwtf.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-08T14:00:45.000Z","updated_at":"2025-03-31T11:01:28.000Z","dependencies_parsed_at":"2025-01-07T18:25:07.113Z","dependency_job_id":"30ac26bf-7799-4011-bf96-ed22fe9b3474","html_url":"https://github.com/cmdwtf/imgui_toggle","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdwtf%2Fimgui_toggle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdwtf%2Fimgui_toggle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdwtf%2Fimgui_toggle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdwtf%2Fimgui_toggle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmdwtf","download_url":"https://codeload.github.com/cmdwtf/imgui_toggle/tar.gz/refs/heads/main","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":["cplusplus","dear-imgui","gui","imgui","widgets"],"created_at":"2025-01-14T19:49:54.711Z","updated_at":"2025-04-13T02:10:38.650Z","avatar_url":"https://github.com/cmdwtf.png","language":"C++","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# 🔘 imgui_toggle\r\n\r\nA small Dear ImGui widget that implements a modern toggle style switch. Requires C++11.\r\n\r\n## Overview\r\n\r\nBased on the discussion in [https://github.com/ocornut/imgui/issues/1537](https://github.com/ocornut/imgui/issues/1537), and on the implementation of `ImGui::Checkbox()`,\r\nthis small widget collection implements a customizable \"Toggle\" style button for Dear ImGui. A toggle represents a boolean on/off much like a checkbox, but is better suited\r\nto some particular paradigms depending on the UI designer's goals. It can often more clearly indicate an enabled/disabled state.\r\n\r\n`imgui_toggle` also supports an optional small animation, similar to that seen in mobile OS and web applications, which can further aid in user feedback.\r\n\r\nInternally, `imgui_toggle` functions very similarly to `ImGui::Checkbox()`, with the exception that it activates on mouse down rather than the release. It supports drawing\r\na label in the same way, and toggling the value by clicking that associated label. The label can be hidden [as on other controls](https://github.com/ocornut/imgui/blob/master/docs/FAQ.md#q-how-can-i-have-widgets-with-an-empty-label).\r\n\r\n## Preview\r\n\r\n![`imgui_toggle` example animated gif](./.meta/imgui_toggle_example.gif)\r\n\r\n_An example of `imgui_toggle`, produced by the [example code](./EXAMPLE.md), as an animated gif._\r\n\r\n## Usage\r\n\r\nAdd the `*.cpp` and `*.h` files to your project, and include `imgui_toggle.h` in the source file you wish to use toggles.\r\n\r\nSee `imgui_toggle.h` for the API, or below for a brief example. As well, [EXAMPLE.md](./EXAMPLE.md) has a more thorough usage example.\r\n\r\n```cpp\r\n\r\nconst ImVec4 green(0.16f, 0.66f, 0.45f, 1.0f);\r\nconst ImVec4 green_hover(0.0f, 1.0f, 0.57f, 1.0f);\r\n\r\nconst ImVec4 gray_dim(0.45f, 0.45f, 0.45f, 1.0f);\r\nconst ImVec4 gray(0.65f, 0.65f, 0.65f, 1.0f);\r\n\r\n// use some lovely gray backgrounds for \"off\" toggles\r\n// the default will use your theme's frame background colors.\r\nImGui::PushStyleColor(ImGuiCol_FrameBg, gray_dim);\r\nImGui::PushStyleColor(ImGuiCol_FrameBgHovered, gray);\r\n\r\nstatic bool values[] = { true, true, true, true, true, true, true, true };\r\nsize_t value_index = 0;\r\n\r\nconst ImVec4 green(0.16f, 0.66f, 0.45f, 1.0f);\r\nconst ImVec4 green_hover(0.0f, 1.0f, 0.57f, 1.0f);\r\nconst ImVec4 salmon(1.0f, 0.43f, 0.35f, 1.0f);\r\nconst ImVec4 green_shadow(0.0f, 1.0f, 0.0f, 0.4f);\r\n\r\n// a default and default animated toggle\r\nImGui::Toggle(\"Default Toggle\", \u0026values[value_index++]);\r\nImGui::Toggle(\"Animated Toggle\", \u0026values[value_index++], ImGuiToggleFlags_Animated);\r\n\r\n// this toggle draws a simple border around it's frame and knob\r\nImGui::Toggle(\"Bordered Knob\", \u0026values[value_index++], ImGuiToggleFlags_Bordered, 1.0f);\r\n\r\n// this toggle draws a simple shadow around it's frame and knob\r\nImGui::PushStyleColor(ImGuiCol_BorderShadow, green_shadow);\r\nImGui::Toggle(\"Shadowed Knob\", \u0026values[value_index++], ImGuiToggleFlags_Shadowed, 1.0f);\r\n\r\n// this toggle draws the shadow \u0026 and the border around it's frame and knob.\r\nImGui::Toggle(\"Bordered + Shadowed Knob\", \u0026values[value_index++], ImGuiToggleFlags_Bordered | ImGuiToggleFlags_Shadowed, 1.0f);\r\nImGui::PopStyleColor(1);\r\n\r\n// this toggle uses stack-pushed style colors to change the way it displays\r\nImGui::PushStyleColor(ImGuiCol_Button, green);\r\nImGui::PushStyleColor(ImGuiCol_ButtonHovered, green_hover);\r\nImGui::Toggle(\"Green Toggle\", \u0026values[value_index++]);\r\nImGui::PopStyleColor(2);\r\n\r\nImGui::Toggle(\"Toggle with A11y Labels\", \u0026values[value_index++], ImGuiToggleFlags_A11y);\r\n\r\n// this toggle shows no label\r\nImGui::Toggle(\"##Toggle With Hidden Label\", \u0026values[value_index++]);\r\n\r\n// pop the FrameBg/FrameBgHover color styles\r\nImGui::PopStyleColor(2);\r\n```\r\n\r\n## Styling\r\n\r\nWhile `imgui_toggle` maintains a simple API for quick and easy toggles, a more complex one exists to allow the user to better customize the widget.\r\n\r\nBy using the overload that takes a `const ImGuiToggleConfig\u0026`, a structure can be provided that provides a multitude of configuration parameters.\r\n\r\nNotably this also allows providing a pointer to a `ImGuiTogglePalette` structure, which allows changing all the colors used to draw the widget. However, this method of configuration is not strictly necessary, as `imgui_toggle` will follow your theme colors as defined below if no palette or color replacement is specified.\r\n\r\n### Theme Colors\r\n\r\nSince `imgui_toggle` isn't part of Dear ImGui proper, it doesn't have any direct references in `ImGuiCol_` for styling. `imgui_toggle` in addition to the method described above, you can use `ImGui::PushStyleColor()` and `ImGui::PopStyleColor()` to adjust the following theme colors around your call to `ImGui::Toggle()`:\r\n\r\n- `ImGuiCol_Text`: Will be used as the color of the knob portion of the toggle, and the color of the accessibility glyph if enabled and \"on\".\r\n- `ImGuiCol_Button`: Will be used as the frame color of the toggle when it is in the \"on\" position, and the widget is not hovered.\r\n- `ImGuiCol_ButtonHovered`: Will be used as the frame color of the toggle when it is in the \"on\" position, and the widget is hovered over.\r\n- `ImGuiCol_FrameBg`: Will be used as the frame color of the toggle when it is in the \"off\" position, and the widget is not hovered. Also used for the color of the accessibility glyph if enabled and \"off\".\r\n- `ImGuiCol_FrameBgHovered`: Will be used as the frame color of the toggle when it is in the \"off\" position, and the widget is hovered over.\r\n- `ImGuiCol_Border`: Will be used as the color drawn as the border on the frame and knob if the related flags are passed.\r\n\r\nUnfortunately, the dark gray and light gray used while the toggle is in the \"off\" position are currently defined by the widget code itself and not by any theme color.\r\n\r\n## Future Considerations\r\n\r\nAs brought up by [ocornut](https://github.com/ocornut/imgui/issues/1537#issuecomment-355562097), if `imgui_toggle` were to be part of mainline Dear ImGui in the future,\r\nthere are some questions that should likely be answered. Most notably for me are the following:\r\n\r\n- Should the toggle get it's own enums in the style system?\r\n  - If so, should which colors should it define, and which would it be okay sharing?\r\n  - If I were choosing, I feel the button and hovered styles as the \"on\" coloring are acceptable, and perhaps adding three more shared styles `ImGuiCol_Knob`, `ImGuiCol_FrameBgOff`, and `ImGuiCol_FrameBgOffHover` for use as the foreground knob color, and the \"off\" background states. (An `Active` may be needed too if switching to operate on input release instead of press.)\r\n- Is the rendering quality good enough?\r\n- Is the dependence on the `LastActiveIdTimer` acceptable for animation, and the user must accept that clicking quickly would skip previous animations?\r\n- Should the toggle behave *exactly* like `ImGui::Checkbox()`, toggling on release rather than press?\r\n\r\n----\r\n\r\n## 📝 License\r\n\r\n`imgui_toggle` is [licensed](./LICENSE) under the Zero-Clause BSD License (SPDX-License-Identifier: 0BSD). If you're interested in `imgui_toggle` under other terms, please contact the author.\r\n\r\nCopyright © 2022 [Chris Marc Dailey](https://cmd.wtf)\r\n\r\nPermission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\r\n\r\n## Acknowledgements\r\n\r\n`imgui_toggle` drew inspiration from [ocornut's original share](https://github.com/ocornut/imgui/issues/1537#issuecomment-355562097),\r\nhis [animated variant](https://github.com/ocornut/imgui/issues/1537#issuecomment-355569554), [nerdtronik's shift to theme colors](https://github.com/ocornut/imgui/issues/1537#issuecomment-780262461),\r\nand [ashifolfi's squircle](https://github.com/ocornut/imgui/issues/1537#issuecomment-1272612641) concept. Inspiration for border drawing came from [moebiussurfing](https://github.com/cmdwtf/imgui_toggle/issues/1#issue-1441329209).\r\n\r\nAs well, inspiration was derived from [Dear ImGui's current `Checkbox` implementation](https://github.com/ocornut/imgui/blob/529cba19b09cf6db206de2b9eaa3152ecb2feff8/imgui_widgets.cpp#L1102),\r\nfor the behavior, label drawing, and hopefully preparing to [handle mixed values/indeterminate states](https://github.com/ocornut/imgui/issues/2644) (albeit unsupported as of yet).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmdwtf%2Fimgui_toggle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmdwtf%2Fimgui_toggle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmdwtf%2Fimgui_toggle/lists"}