{"id":16036499,"url":"https://github.com/gherardovarando/electrongui","last_synced_at":"2025-03-18T04:30:25.371Z","repository":{"id":57222025,"uuid":"86041037","full_name":"gherardovarando/electrongui","owner":"gherardovarando","description":"Framework to create GUI with electron","archived":false,"fork":false,"pushed_at":"2019-02-04T15:53:42.000Z","size":952,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-28T06:55:21.995Z","etag":null,"topics":["electron","gui","node","photon"],"latest_commit_sha":null,"homepage":"","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/gherardovarando.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":"2017-03-24T07:45:55.000Z","updated_at":"2021-02-12T15:18:42.000Z","dependencies_parsed_at":"2022-09-04T04:50:30.487Z","dependency_job_id":null,"html_url":"https://github.com/gherardovarando/electrongui","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/gherardovarando%2Felectrongui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherardovarando%2Felectrongui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherardovarando%2Felectrongui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherardovarando%2Felectrongui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gherardovarando","download_url":"https://codeload.github.com/gherardovarando/electrongui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243902240,"owners_count":20366258,"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":["electron","gui","node","photon"],"created_at":"2024-10-08T22:05:06.151Z","updated_at":"2025-03-18T04:30:24.968Z","avatar_url":"https://github.com/gherardovarando.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# electrongui\n\n[![npm version](https://badge.fury.io/js/electrongui.svg)](https://badge.fury.io/js/electrongui)\n[![MIT Licence](https://badges.frapsoft.com/os/mit/mit.png?v=103)](https://opensource.org/licenses/mit-license.php)\n#### [gherardo.varando@gmail.com](mailto:gherardo.varando@gmail.com)\n\n**From v1.0.0 we will try :innocent: to follow semver MAJOR.MINOR.PATCH**\n\n**electrongui** is a skeleton for GUI written in JS/Node/electron framework. It is made of several classes and utilities. The main class is `Gui` that creates an empty interface on the current window. It is not compulsory to create an instance of `Gui` class and every other classes and utilities can be used independently. `electrongui` is meant to be used in Rendered windows and **not** in the main electron process.\n\n**electrongui** bundles now npm to install extensions.\n\nYou can download a basic electrongui distribution, that is a working application based on electrongui [here](https://github.com/gherardovarando/electrongui-dist/releases)\n## How to use it\n\n- Install electrongui with `npm`\n\n- In the Renderer process of your electron app:\n\n ```\nconst {Gui} = require('electrongui')\nlet gui = new Gui() // create the base gui structure\ngui.alerts.add('Gui initialized!!!','warning') //this message should appear in the footer\n ```\n\n- See the [API](https://gherardovarando.github.io/electrongui/API.html)\n\n\n## How to write extensions\n\nTo write an extension you just need to create a npm package (or a simple js file) exporting a `class` that extend the `GuiExtension` class.\n\n```\nconst {\n  GuiExtension,\n  util\n} = require('electrongui')\n\nclass MyExtension extends GuiExtension {\n\n  constructor(gui) {\n    super(gui, {\n      icon: 'fa fa-bars',\n      // alternatively image: 'path-to-image',\n      //setting a manuLabel and a menuTemplate\n      menuLabel: 'MyExtension',\n      menuTemplate: [{\n        label: 'Show',\n        click: () =\u003e this.show()\n      }, {\n        label: 'action'\n      }, {\n        label: 'other action'\n      }]\n    })\n  }\n\n  activate() {\n    super.activate() //always call super methods\n    this.appendMenu()\n    // here goes the creation of the elements\n    this.appendChild(util.div('padded', 'This is the main element of MyExtension'))\n    this.gui.alerts.add('MyExtension activated')\n  }\n\n  deactivate() {\n    super.deactivate() // clean main pane and menu\n    //clean other things that could have been added\n    util.notifyOS('MyExtension deactivated')\n  }\n}\n\nmodule.exports = MyExtension\n```\n\n\n### The `gui` object\n\nThe current `gui` interface (instance of `Gui`) it is passed automatically on creation. And can be obtained with `this.gui` (see example above).\n\n### Requiring modules\n\nYou can require Node native modules and Electron ones. Every dependencies that you need can be loaded with `require`. Be sure to list `electrongui` as a dependency.\n\n##### Using the `module.parent.require` trick\nIf your extension is very simple and do not use any external modules apart from `electrongui` it can be written requiring `electrongui` from the parent module.\nThis method permit to install extension from single files, without the need to install additional packages.\n\n```\n//myextension.js\nconst {GuiExtension} = module.parent.require('electrongui') // this will require electrongui from the parent module, since the parent moduel is in the application it will find electrongui module.\n\nclass MyExtension extends GuiExtension {\n  constructor(gui){\n    super(gui,{\n      icon: 'fa fa-bar'\n      })\n    // etc..\n  }\n}\n\nmodule.exports = MyExtension\n```\n\n### Installing the extension\n\nIf you want then to integrate your extension in the application, you can directly insert it as a dependency in the `package.json` of the electron app and then create the instance and call the `activate` method (see example below).\n\n```\n//renderer.js\nconst {Gui} = require('electrongui')\nconst MyExtension = require('myextension')\n\nlet gui = new Gui()\n\nlet myext = new MyExtension\nmyext.activate()\n```\n\n\n#### Using the built-in `ExtensionsManager`\n\nThe extensions manager instance is available through `gui.extensions` and provides methods to install and manage extensions. If you want to install an extension with the extension manager (useful for developing new extensions), the extension need to be able to find all the dependencies, especially `electrongui`. It is suggested to create a npm-module folder structure for the extension, an appropriate `package.json`. Running `npm install` will build the `node_modules` folder containing all the dependencies.\n\n##### Using ExtensionsManager programmatically\n\n```\nconst {Gui} = require('electrongui')\nlet gui = new Gui()\n\n// create alert if the ExtensionsManager run in an error, this is useful when\n// ExtensionsManager find an error loading an extension\ngui.extensions.on('error',(e)=\u003e{\n  gui.alerts.add(e.message, 'danger')\n  console.log(e)\n  })\n\n// the following will load the extension file with require, then will try to create the extension\ngui.extensions.load('myextensionpath') // path to MyExtension.js or to appropriate\n                                      //  package.json or just module name if\n                                      //  the extension is a npm module and it is                                    \n                                      //  installed in a location reachable from\n                                      //  the electron app renderer process.\n// now the extension is available\n\ngui.extensions.extensions.MyExtension.activate()\n\n```\n\n##### Using ExtensionsManager from the GUI\n\nExtensionsManager is a GuiExtension and provide also GUI element to operate on extensions.\nIt is possoble to load a local extension or to download and install an extension from **npm**\nTo use it from the GUI it is necessary to activate it.\n\n```\nconst {Gui} = require('electrongui')\nlet gui = new Gui()\n\ngui.extensions.activate()\n// now there will be a new menu entry in the application named Extensions\n// from there it is possible to install new extensions, selecting the main js file or from npm\n// moreover it is possible to activate/deactivate extensions\n```\n\n\n### Cleaning the interface on deactivate\n\nThe `deactivate` method must clean all the elements added to the interfaces as buttons or menus. The menu created by the menuLabel and menuTemplate options in the creation are automatically removed by `super.deactivate()`. Moreover the `deactivate` method must also remove the event listener added.\n\n\n## Acknowledgment\n\nMario Juez [mjuez@fi.upm.es](mailto:mjuez@fi.upm.es) collaborated in part of the code.  \nThis project was partially founded by the\n[Cajal Blue Brain Project](http://cajalbbp.cesvima.upm.es/)\nuntil march 2018.\n\n## License\n\nCopyright (c) 2017 Gherardo Varando (gherardo.varando@gmail.com)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgherardovarando%2Felectrongui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgherardovarando%2Felectrongui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgherardovarando%2Felectrongui/lists"}