Some of the repetitive violations were suppressed.
7.12KiB; Markdown | 2020-01-29 08:53:46+01 | SLOC 135
1 1
# Custom Electron Titlebar␣
2 1
3 1
This project is a typescript library for electron that allows you to configure a fully customizable title bar.␣
4 1
5 1
### **It is a library for electron, it cannot be used on a basic website.**␣
6 1
7 1
[![LICENSE](https://img.shields.io/github/license/AlexTorresSk/custom-electron-titlebar.svg)](https://github.com/AlexTorresSk/custom-electron-titlebar/blob/master/LICENSE)␣
8 1
[![NPM Version](https://img.shields.io/npm/v/custom-electron-titlebar.svg)](https://npmjs.org/package/custom-electron-titlebar)␣
9 1
10 1
![Preview 1](screenshots/window_1.png)␣
11
12
![Preview 2](screenshots/window_2.png)␣
13
14
![Preview 3](screenshots/window_3.png)␣
15
16
## Install␣
17
18
```␣
19
npm i custom-electron-titlebar␣
20
```␣
21
22
Or␣
23
24
```␣
25
npm install custom-electron-titlebar@latest␣
26
```␣
27
28
## Usage␣
29
30
In your **renderer** file or in an **HTML script tag** add:␣
31
32
```js␣
33
const customTitlebar = require('custom-electron-titlebar');␣
34
35
new customTitlebar.Titlebar({␣
36
	backgroundColor: customTitlebar.Color.fromHex('#444')␣
37
});␣
38
```␣
39
40
> if you are using _typescript_␣
41
```ts␣
42
import { Titlebar, Color } from 'custom-electron-titlebar'␣
43
44
new Titlebar({␣
45
	backgroundColor: Color.fromHex('#ECECEC')␣
46
});␣
47
```␣
48
49
The parameter `backgroundColor: Color` is required, this should be `Color` type.␣
50
(View [Update Background](#update-background) for more details).␣
51
52
## Options␣
53
54
The interface [`TitleBarOptions`] is managed, which has the following configurable options for the title bar. Some parameters are optional.␣
55
56
| Parameter                | Type             | Description                                                                           | Default                   |␣
57
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------- | ------------------------- |␣
58
| backgroundColor **(required)** | Color            | The background color of the titlebar.                                                 | #444444     |␣
59
| icon                     | string           | The icon shown on the left side of the title bar.                                     | null                      |␣
60
| iconsTheme               | Theme            | Style of the icons.                                                                   | Themebar.win              |␣
61
| shadow                   | boolean          | The shadow of the titlebar.                                                           | false                     |␣
62
| drag                     | boolean          | Define whether or not you can drag the window by holding the click on the title bar.  | true                      |␣
63
| minimizable              | boolean          | Enables or disables the option to minimize the window by clicking on the corresponding button in the title bar.                                    | true                      |␣
64
| maximizable              | boolean          | Enables or disables the option to maximize and un-maximize the window by clicking on the corresponding button in the title bar.                      | true                      |␣
65
| closeable                | boolean          | Enables or disables the option of the close window by clicking on the corresponding button in the title bar.                                       | true                      |␣
66
| order                    | string           | Set the order of the elements on the title bar. (`inverted`, `first-buttons`)         | null                      |␣
67
| titleHorizontalAlignment | string           | Set horizontal alignment of the window title. (`left`, `center`, `right`)             | center                    |␣
68
| menu                     | Electron.Menu    | The menu to show in the title bar.                                                    | Menu.getApplicationMenu() |␣
69
| menuPosition             | string           | The position of menubar on titlebar.                                                  | left 											|␣
70
| enableMnemonics          | boolean 					| Enable the mnemonics on menubar and menu items.																				| true											|␣
71
| itemBackgroundColor      | Color            | The background color when the mouse is over the item.                                 | rgba(0, 0, 0, .14)        |␣
72
| hideWhenClickingClose | boolean | When the close button is clicked, the window is hidden instead of closed. | false |␣
73
| overflow                 | string            | The overflow of the container (`auto`, `visible`, `hidden`)         | auto␣
74
75
## Methods␣
76
77
### Update Background␣
78
79
When this method is executed, as well as when the title bar is created, it is checked whether the color is light or dark, so that the color of the icons adapts to the background of the title bar.␣
80
81
```js␣
82
titlebar.updateBackground(new Color(new RGBA(0, 0, 0, .7)));␣
83
```␣
84
85
To assign colors you can use the following options: `Color.fromHex()`, `new Color(new RGBA(r, g, b, a))`, `new Color(new HSLA(h, s, l, a))`, `new Color(new HSVA(h, s, v, a))` or `Color.BLUE`, `Color.RED`, etc.␣
86
87
### Update Title␣
88
89
This method updated the title of the title bar, If you change the content of the `title` tag, you should call this method for update the title.␣
90
91
```js␣
92
document.title = 'My new title';␣
93
titlebar.updateTitle();␣
94
95
// Or you can do as follows and avoid writing document.title␣
96
titlebar.updateTitle('New Title');␣
97
```␣
98
99
if this method is called and the title parameter is added, the title of the document is changed to that of the parameter.␣
100
101
### Update Icon␣
102
103
With this method you can update the icon. This method receives the url of the image _(it is advisable to use transparent image formats)_␣
104
105
```js␣
106
titlebar.updateIcon('./images/my-icon.svg');␣
107
```␣
108
109
### Update Menu␣
110
111
This method updates or creates the menu, to create the menu use remote.Menu and remote.MenuItem.␣
112
113
```js␣
114
const menu = new Menu();␣
115
menu.append(new MenuItem({␣
116
	label: 'Item 1',␣
117
	submenu: [␣
118
		{␣
119
			label: 'Subitem 1',␣
120
			click: () => console.log('Click on subitem 1')␣
121
		},␣
122
		{␣
123
			type: 'separator'␣
124
		}␣
125
	]␣
126
}));␣
127
128
menu.append(new MenuItem({␣
129
	label: 'Item 2',␣
130
	submenu: [␣
131
		{␣
132
			label: 'Subitem checkbox',␣
133
			type: 'checkbox',␣
134
			checked: true␣
135
		},␣
136
		{␣
137
			type: 'separator'␣
138
		},␣
139
		{␣
140
			label: 'Subitem with submenu',␣
141
			submenu: [␣
142
				{␣
143
					label: 'Submenu &item 1',␣
144
					accelerator: 'Ctrl+T'␣
145
				}␣
146
			]␣
147
		}␣
148
	]␣
149
}));␣
150
151
titlebar.updateMenu(menu);␣
152
```␣
153
154
### Update Menu Position␣
155
156
You can change the position of the menu bar. `left` and `bottom` are allowed.␣
157
158
```js␣
159
titlebar.updateMenuPosition('bottom');␣
160
```␣
161
162
### Set Horizontal Alignment␣
163
164
> setHorizontalAlignment method was contributed by [@MairwunNx](https://github.com/MairwunNx) :punch:␣
165
166
`left`, `center` and `right` are allowed␣
167
168
```js␣
169
titlebar.setHorizontalAlignment('right');␣
170
```␣
171
172
### Dispose␣
173
174
This method removes the title bar completely and all recorded events.␣
175
176
```js␣
177
titlebar.dispose();␣
178
```␣
179
180
## Contributing␣
181
182
Many thanks to all the people who support this project through issues and pull request.␣
183
If you want to contribute with this project, all the issues and pull request are welcome.␣
184
185
## License␣
186
187
This project is under the [MIT](https://github.com/AlexTorresSk/custom-electron-titlebar/blob/master/LICENSE) license.␣