1 | # electron-window-state [![Build Status](https://travis-ci.org/mawie81/electron-window-state.svg)](https://travis-ci.org/mawie81/electron-window-state)
|
2 |
|
3 | > A library to store and restore window sizes and positions for your
|
4 | [Electron](http://electron.atom.io) app
|
5 |
|
6 | *Heavily influenced by the implementation in [electron-boilerplate](https://github.com/szwacz/electron-boilerplate).*
|
7 |
|
8 | ## Install
|
9 |
|
10 | ```
|
11 | $ npm install --save electron-window-state
|
12 | ```
|
13 |
|
14 | ## Usage
|
15 |
|
16 | ```js
|
17 | const windowStateKeeper = require('electron-window-state');
|
18 | let win;
|
19 |
|
20 | app.on('ready', function () {
|
21 | // Load the previous state with fallback to defaults
|
22 | let mainWindowState = windowStateKeeper({
|
23 | defaultWidth: 1000,
|
24 | defaultHeight: 800
|
25 | });
|
26 |
|
27 | // Create the window using the state information
|
28 | win = new BrowserWindow({
|
29 | 'x': mainWindowState.x,
|
30 | 'y': mainWindowState.y,
|
31 | 'width': mainWindowState.width,
|
32 | 'height': mainWindowState.height
|
33 | });
|
34 |
|
35 | // Let us register listeners on the window, so we can update the state
|
36 | // automatically (the listeners will be removed when the window is closed)
|
37 | // and restore the maximized or full screen state
|
38 | mainWindowState.manage(win);
|
39 | });
|
40 | ```
|
41 |
|
42 | ## API
|
43 |
|
44 | #### windowStateKeeper(opts)
|
45 |
|
46 | Note: Don't call this function before the `ready` event is fired.
|
47 |
|
48 | ##### opts
|
49 |
|
50 | `defaultWidth` - *Number*
|
51 |
|
52 | The width that should be returned if no file exists yet. Defaults to `800`.
|
53 |
|
54 | `defaultHeight` - *Number*
|
55 |
|
56 | The height that should be returned if no file exists yet. Defaults to `600`.
|
57 |
|
58 | `path` - *String*
|
59 |
|
60 | The path where the state file should be written to. Defaults to
|
61 | `app.getPath('userData')`
|
62 |
|
63 | `file` - *String*
|
64 |
|
65 | The name of file. Defaults to `window-state.json`
|
66 |
|
67 | `maximize` - *Boolean*
|
68 |
|
69 | Should we automatically maximize the window, if it was last closed
|
70 | maximized. Defaults to `true`
|
71 |
|
72 | `fullScreen` - *Boolean*
|
73 |
|
74 | Should we automatically restore the window to full screen, if it was last
|
75 | closed full screen. Defaults to `true`
|
76 |
|
77 | ### state object
|
78 |
|
79 | ```js
|
80 | const windowState = windowStateKeeper({
|
81 | defaultWidth: 1000,
|
82 | defaultHeight: 800
|
83 | });
|
84 | ```
|
85 |
|
86 | `x` - *Number*
|
87 |
|
88 | The saved `x` coordinate of the loaded state. `undefined` if the state has not
|
89 | been saved yet.
|
90 |
|
91 | `y` - *Number*
|
92 |
|
93 | The saved `y` coordinate of the loaded state. `undefined` if the state has not
|
94 | been saved yet.
|
95 |
|
96 | `width` - *Number*
|
97 |
|
98 | The saved `width` of loaded state. `defaultWidth` if the state has not been
|
99 | saved yet.
|
100 |
|
101 | `height` - *Number*
|
102 |
|
103 | The saved `heigth` of loaded state. `defaultHeight` if the state has not been
|
104 | saved yet.
|
105 |
|
106 | `isMaximized` - *Boolean*
|
107 |
|
108 | `true` if the window state was saved while the the window was maximized.
|
109 | `undefined` if the state has not been saved yet.
|
110 |
|
111 | `isFullScreen` - *Boolean*
|
112 |
|
113 | `true` if the window state was saved while the the window was in full screen
|
114 | mode. `undefined` if the state has not been saved yet.
|
115 |
|
116 | `manage(window)` - *Function*
|
117 |
|
118 | Register listeners on the given `BrowserWindow` for events that are
|
119 | related to size or position changes (`resize`, `move`). It will also restore
|
120 | the window's maximized or full screen state.
|
121 | When the window is closed we automatically remove the listeners and save the
|
122 | state.
|
123 |
|
124 | `unmanage` - *Function*
|
125 |
|
126 | Removes all listeners of the managed `BrowserWindow` in case it does not
|
127 | need to be managed anymore.
|
128 |
|
129 | `saveState(window)` - *Function*
|
130 |
|
131 | Saves the current state of the given `BrowserWindow`. This exists mostly for
|
132 | legacy purposes, and in most cases it's better to just use `manage`.
|
133 |
|
134 | ## License
|
135 |
|
136 | MIT © [Marcel Wiehle](http://marcel.wiehle.me)
|