Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rhysd/electron-about-window

'About This App' mini-window for Electron apps
https://github.com/rhysd/electron-about-window

electron utility

Last synced: 2 days ago
JSON representation

'About This App' mini-window for Electron apps

Awesome Lists containing this project

README 

        
'About This App' Window for [Electron](https://github.com/atom/electron) Apps

=============================================================================

[![npm version](https://badge.fury.io/js/about-window.svg)](https://www.npmjs.com/package/about-window)



[This package](https://www.npmjs.com/package/about-window) provides 'About This App' window for [Electron](https://github.com/atom/electron) applications.



- [x] Create 'About This App' window from given parameters

  - [x] Icon path

  - [x] Copy right

  - [x] App name and Versions

  - [x] Description

- [x] Gather package information from package.json

- [x] Automatically detect package.json

- [x] Adjust window size to its contents automatically

- [x] Optional close button

- [x] CSS customizability



You can install this module via [npm](https://www.npmjs.com/).



```sh

$ npm install about-window

```



## Usage



Only one function is exported as default.  Please see [TypeScript type definition](index.d.ts).

The function can be called from both main process and renderer process.



```typescript

export default function openAboutWindow(info: {

    icon_path: string;

    product_name?: string;

    package_json_dir?: string;

    about_page_dir?: string;

    bug_report_url?: string;

    bug_link_text?: string;

    copyright?: string;

    homepage?: string;

    description?: string;

    license?: string;

    css_path?: string | string[];

    adjust_window_size?: boolean;

    win_options?: BrowserWindowOptions;

    use_version_info?: boolean | [string, string][];

    show_close_button?: string;

    app?: Electron.App;

    BrowserWindow?: typeof Electron.BrowserWindow;

    ipcMain?: Electron.IpcMain;

}): BrowserWindow

```



Only `icon_path` property is required, others are optional.

I recommend to specify as below to extract information from package.json as much as possible.

Path to package.json is also automatically detected if possible.



```typescript

openAboutWindow({

    icon_path: 'path/to/icon.png'

});

```



If `string` value is passed to the first parameter, it is passed to `icon_path`. So following is a shorthand of above code:



```typescript

openAboutWindow('path/to/icon.png');

```



You can check [an example app](example) to know how to use this package.



```sh

$ git clone https://github.com/rhysd/about-window.git

$ cd about-window/example

$ npm install

$ npm start



# Or for debug

$ npm run debug

```



### Parameter's properties of `openAboutWindow()`



| Name | Description | Type |

|------|-------------|------|

| `icon_path` | Path to icon file of the application. The path is passed to `src` property of `` element. **Required** | string |

| `package_json_dir` | Path to directory which contains package.json.  If not specified, it will try to detect a path to package.json.  If also failed, it gives up and show less information in 'About This App' window. **Optional** | string |

| `bug_report_url` | URL to bug report page.  If not specified, 'bugs' entry in package.json is used. **Optional** | string |

| `copyright` | Copyright notice shown in window.  If not specified, it is replaced with license description generated by 'license' entry of package.json. **Optional** | string |

| `homepage` | URL of application's web page.  If not specified, 'homepage' entry of package.json is used instead. **Optional** | string |

| `description` | Description of the application.  If not specified, 'description' entry of package.json is used instead. **Optional** | string |

| `license` | License of the application.  If not specified, 'license' entry of package.json is used instead. This property is used when `copyright` is not specified. **Optional** | string |

| `win_options` | Options of 'About This App' window.  It is merged into default options. **Optional** | [BrowserWindow options object](https://github.com/atom/electron/blob/master/docs/api/browser-window.md#new-browserwindowoptions) |

| `css_path` | Path(s) to user-defined CSS file.  It will be inserted to DOM of the window. **Optional** | (array of) string |

| `adjust_window_size` | Adjust the window size to its content not to show scroll bar. **Optional** | boolean |

| `open_devtools` | For debug purpose, Chrome DevTools will start when the window is opened. **Optional** | boolean |

| `use_inner_html` | If `true`, set the value with `.innerHTML` on copyright, license and description Default is `false`. **Optional** | boolean |

| `bug_link_text` | Text for a bug report link. **Optional** | string |

| `product_name` | Name of the application **Optional** | string |

| `use_version_info` | If is `false`, nothing will be displayed, if is `true`, the versions of electron, chrome, node, and v8 will be displayed, if is an array of string tuple, its entries will be displayed. Default is `true`. **Optional** | boolean |

| `show_close_button` | If this is a valid string, a close button with this string be displayed. **Optional** | string |

| `about_page_dir` | Directory path which contains `about.html` which is rendered in 'About this app' window. **Optional** | string |

| `app` | [app](https://www.electronjs.org/docs/latest/api/app) instance to use. This property is necessary only when using on renderer processes. **Optional** | Electron.App |

| `BrowserWindow` | Constructor of [BrowserWindow](https://www.electronjs.org/docs/latest/api/browser-window) to use. This property is necessary only when using on renderer processes. **Optional** | Electron.BrowserWindow |

| `ipcMain` | [ipcMain](https://www.electronjs.org/docs/latest/api/ipc-main) instance to use. This property is necessary only when using on renderer processes. **Optional** | Electron.IpcMain |



**Note:** If you set `use_inner_html` to `true`, please ensure that contents don't contain any untrusted external input

in order to avoid XSS. Be careful.



### Open the window from non-main process



Since `openAboutWindow()` depends on several APIs only available on main process, they must be provided by caller when it is called on non-main process.



To mimic the APIs, use [`@electron/remote`](https://www.npmjs.com/package/@electron/remote) module.



```typescript

import {app, BrowserWindow, ipcMain} from '@electron/remote';



openAboutWindow({

    icon_path: 'path/to/icon.png'

    app,

    BrowserWindow,

    ipcMain,

});

```



## Screen Shots



### Linux



![Linux screenshot](https://raw.githubusercontent.com/rhysd/ss/master/about-window/about-window-linux.png)



### OS X



![OS X screenshot](https://raw.githubusercontent.com/rhysd/ss/master/about-window/about-window-os-x.png)



### Windows



![Windows screenshot](https://raw.githubusercontent.com/rhysd/ss/master/about-window/about-window-windows.jpg)



## License



[MIT License](/LICENSE.txt).