From 8caf5fac0600e0235403adc477a51160f898f3d6 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Mon, 9 Sep 2013 14:52:46 +0800 Subject: [PATCH] doc: Document frameless window. --- docs/browser-window.md | 6 ++++ docs/frameless-window.md | 62 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 docs/frameless-window.md diff --git a/docs/browser-window.md b/docs/browser-window.md index f197e59acb7c..54eee64af437 100644 --- a/docs/browser-window.md +++ b/docs/browser-window.md @@ -15,6 +15,10 @@ win.loadUrl('https://github.com'); win.show(); ``` +You can also create a window without chrome by using +[Frameless Window](frameless-window.md) API. + + **Note:** Be careful not to use `window` as the variable name. ## Class: BrowserWindow @@ -38,6 +42,8 @@ win.show(); * `kiosk` Boolean - The kiosk mode * `title` String - Default window title * `show` Boolean - Whether window should be shown when created + * `frame` Boolean - Specify `false` to create a + [Frameless Window](frameless-window.md) Creates a new `BrowserWindow` with native properties set by the `options`. Usually you only need to set the `width` and `height`, other properties will diff --git a/docs/frameless-window.md b/docs/frameless-window.md new file mode 100644 index 000000000000..5a2133acf9b1 --- /dev/null +++ b/docs/frameless-window.md @@ -0,0 +1,62 @@ +A frameless window is a window that has no chrome. + +## Create a frameless window + +To create a frameless window, you only need to specify `frame` to `false` in +[BrowserWindow](browser-window.md)'s `options`: + + +```javascript +var BrowserWindow = require('browser-window'); +var win = new BrowserWindow({ width: 800, height: 600, frame: false }); +``` + +## Draggable region + +By default, the frameless window is non-draggable. Apps need to specify +`-webkit-app-region: drag` in CSS to tell atom-shell which regions are draggable +(like the OS's standard titlebar), and apps can also use +`-webkit-app-region: no-drag` to exclude the non-draggable area from the + draggable region. Note that only rectangular shape is currently supported. + +To make the whole window draggable, you can add `-webkit-app-region: drag` as +`body`'s style: + +```html + + +``` + +And note that if you have made the whole window draggable, you must also mark +buttons as non-draggable, otherwise it would be impossible for users to click on +them: + +```css +button { + -webkit-app-region: no-drag; +} +``` + +If you're only using a custom titlebar, you also need to make buttons in +titlebar non-draggable. + +## Text selection + +One thing on frameless window is that the dragging behaviour may conflict with +selecting text, for example, when you drag the titlebar, you may accidentally +select the text on titlebar. To prevent this, you need to disable text +selection on dragging area like this: + +```css +.titlebar { + -webkit-user-select: none; + -webkit-app-region: drag; +} +``` + +##Context menu + +On some platforms, the draggable area would be treated as non-client frame, so +when you right click on it a system menu would be popuped. To make context menu +behave correctly on all platforms, you should never custom context menu on +draggable areas.