{"id":13730125,"url":"https://github.com/ffAudio/foleys_gui_magic","last_synced_at":"2025-05-08T02:31:24.993Z","repository":{"id":37550341,"uuid":"209666033","full_name":"ffAudio/foleys_gui_magic","owner":"ffAudio","description":"A GUI builder module for JUCE - with examples","archived":false,"fork":false,"pushed_at":"2024-05-22T15:00:39.000Z","size":2861,"stargazers_count":317,"open_issues_count":10,"forks_count":44,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-05-22T23:29:31.574Z","etag":null,"topics":["generic-editor","gui","juce","meters","pluginguimagic","stylesheet","wyswyg"],"latest_commit_sha":null,"homepage":"https://foleysfinest.com/developer/pluginguimagic/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ffAudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2019-09-19T23:33:25.000Z","updated_at":"2024-08-03T02:23:08.401Z","dependencies_parsed_at":"2023-02-11T21:45:37.075Z","dependency_job_id":"dee9def3-ee2b-4de0-a00a-0e6b51e9850a","html_url":"https://github.com/ffAudio/foleys_gui_magic","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffAudio%2Ffoleys_gui_magic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffAudio%2Ffoleys_gui_magic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffAudio%2Ffoleys_gui_magic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffAudio%2Ffoleys_gui_magic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ffAudio","download_url":"https://codeload.github.com/ffAudio/foleys_gui_magic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224689365,"owners_count":17353369,"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":["generic-editor","gui","juce","meters","pluginguimagic","stylesheet","wyswyg"],"created_at":"2024-08-03T02:01:10.237Z","updated_at":"2024-11-14T20:31:50.213Z","avatar_url":"https://github.com/ffAudio.png","language":"C++","readme":"foleys_gui_magic\n===============\n\nDEPRECATION:\nthe branch `develop` won't be updated and will be deleted soon.    \nThe development is done in feature branches which are merged directly to `main`, so you can always fast-forward the main branch.\n\nmain:    \n[![CMake](https://github.com/ffAudio/foleys_gui_magic/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/ffAudio/foleys_gui_magic/actions/workflows/build.yml)    \n\nThis module allows to create GUIs without any coding. It is created with a DOM model\nthat provides a hierarchical information, and a CSS cascading stylesheet to define\nrules for the appearance of the GUI.\n\nThere is a drag and drop editor to add GUI elements, and to connect to\nparameters of your AudioProcessor. Also an editor in the style of FireBug\nto investigate the individual properties, and how they were obtained/calculated.\n\nRepository map\n--------------\n\nThe module to add to your project is in `modules/foleys_gui_magic`. Ideally you just use the `juce_add_module()` in your CMakeLists.txt or add it via Projucer.\n\nIn the folder `Examples` you find the example projects. The build will run pluginval on the examples (where it applies).    \nThe CMake option for the examples is `FOLEYS_BUILD_EXAMPLES` and for pluginval `FOLEYS_RUN_PLUGINVAL`.\n\nIn `Tests` there are the Catch2 unit tests. Each build will run those unit tests against the latest version.    \nThe CMake option for the unit tests is `FOLEYS_BUILD_TESTS`.\n\nCMake will be responsible to fetch JUCE, pluginval and Catch2 if switched on.\n\nSupport\n-------\n\nYou can find the api docs in https://foleysfinest.com/foleys_gui_magic/\n\nFor the modules of Foleys Finest Audio there is a new forum where you can search for information \nand ask questions: https://forum.foleysfinest.com\n\nOr join the discussion on [discord](https://discord.gg/Xhn58BrAjG)\n\nAll feedback is welcome.\n\nSetup\n-----\n\nTo use the WYSWYG plugin editor, add this module via Projucer or CMake to your JUCE project.\n\nInstead of inheriting from juce::AudioProcessor inherit foleys::MagicProcessor.\nGet rid of those methods:\n- bool hasEditor()\n- juce::PluginEditor* createEditor()\n- void setStateInformation() and void getStateInformation() (optional, a default saving and loading method is provided)\n\nThe foleys::MagicProcessor will provide a `foleys::MagicProcessorState magicState` (protected visibility) \nto add visualisations or other objects to expose to the GUI.\n\nThe floating editor has an auto save, which needs to know the location of your source files. To activate that\nyou need to copy this macro into your foleys::MagicProcessor constructor:\n```cpp\nFOLEYS_SET_SOURCE_PATH(__FILE__);\n```\nOtherwise autosave will start working once you loaded or saved the state, since then the editor has a location to use.\n\nIt is also possible to use the module in an Application. In that case you add a `MagicGuiState` and a `MagicGUIBuilder` yourself.\nThere is an example available in the examples repository called PlayerExample.\n\n\nAdd Visualisations\n------------------\n\nTo add visualisations like an Analyser or Oscilloscope to your plugin, add them in the constructor:\n\n```\n// Member:\nfoleys::MagicPlotSource* analyser = nullptr;\n\n// Constructor\nanalyser = magicState.createAndAddObject\u003cfoleys::MagicAnalyser\u003e(\"input\");\n\n// prepareToPlay\nanalyser-\u003eprepareToPlay (sampleRate, samplesPerBlockExpected);\n\n// e.g. in processBlock send the samples to the analyser:\nanalyser-\u003epushSamples (buffer);\n```\n\nIn your editor, drag a `Plot` component into the UI and select the name you supplied as `source`, in this\ncase \"input\".\n\n\nSaving and restoring the plugin\n-------------------------------\n\nThe `foleys::MagicProcessor` takes care of saving and restoring the parameters and properties.\nYou can add your own values to the ValueTree in the `magicState`.\nThere is a callback after restoring that you can override, in case you need to do some additional action.\n\nAdditionally to saving the values in the plugin state you can have settings across all instances of your plugin.\nTo use that you need to setup the path to a file. After that the settings are synchronised in the\nsettings of the magicState:\n```\n// in constructor\nmagicState.setApplicationSettingsFile (juce::File::getSpecialLocation (juce::File::userApplicationDataDirectory)\n                                       .getChildFile (ProjectInfo::companyName)\n                                       .getChildFile (ProjectInfo::projectName + juce::String (\".settings\")));\n\n// use it like\npresetNode = magicState.getSettings().getOrCreateChildWithName (\"presets\", nullptr);\npresetNode.setProperty (\"foo\", 100, nullptr);\n```\n\nOther than the juce::ApplicationSettings this is not a flat list but can deal with hierarchical data in form of ValueTrees.\nPluginGuiMagic will deal with interprocess safety and update if the file has changed.\n\nBake in the xml\n---------------\n\nTo bake in the GUI save the XML from the PGM panel and add it to the BinaryResources via Projucer.\nIn the constructor you set the XML file:\n```\nmagicState.setGuiValueTree (BinaryData::magic_xml, BinaryData::magic_xmlSize);\n```\n\n\nRemoving the WYSWYG editor\n--------------------------\n\nThe WYSWYG editor panel (attached outside the PluginEditor) is switched on or off with the config\nin Projucer named `FOLEYS_SHOW_GUI_EDITOR_PALLETTE`. An effective way is to add `FOLEYS_SHOW_GUI_EDITOR_PALLETTE=0`\ninto extra preprocessor defines of the release build, that way you can design in debug mode, and avoid\nthe WYSWYG editor from being included in the release build for deployment.\n\n\nCurrently available Components\n------------------------------\n\nIt is completely possible to register your own bespoke Components into the builder. These Components\nare already available:\n\n - Slider (attachable to parameters)\n - ComboBox (attachable to parameters)\n - ToggleButton (attachable to parameters)\n - TextButton (attachable to parameters)\n - XYDragComponent (attachable to two parameters)\n - Plot (displays various 2-d data)\n - LevelMeter (displays different RMS / Max levels)\n - Label\n - MidiKeyboardComponent\n - MidiLearn\n - ListBox\n - WebBrowserComponent\n\nAll Components have the option to add margins/paddings and a border also with rounded corners.\nThe View component serves as container, that has the option to layer all child components on top of each other\nor to layout them using flex-box.\n\n\nDemo projects\n-------------\n\nYou find the demo projects in the folder `Examples`. We use CMake for building the examples and running the unit tests.\n\nContributing\n------------\n\nEverybody is welcome and encouraged to contribute. This is supposed to be helpful for as \nmany people as possible, so please give your ideas as github issues and send pull requests.\n\nWe might ask you to change things in your pull requests to keep the style consistent and\nto keep the API as concise as possible.\n\nWe have a discord server to discuss features, bugs or ideas:  \n[Discord](https://discord.gg/gxtjTx6fNg)\n\nIf you make changes, make sure that the unit tests in `Tests` still succeed and the examples in the `Examples` folder still compile and work.\n\nGood luck and happy coding, erm designing, erm... both actually :-)\n\n\nBrighton, UK - started Sept. 2019\nEsslingen, Germany - 2020 - 2023\n","funding_links":[],"categories":["UI"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FffAudio%2Ffoleys_gui_magic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FffAudio%2Ffoleys_gui_magic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FffAudio%2Ffoleys_gui_magic/lists"}