From: Cheng Zhao Date: Fri, 18 Sep 2015 04:01:33 +0000 (+0800) Subject: Merge branch 'master' of https://github.com/MaxWhere/electron into MaxWhere-master X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=ee0d48dc5a3beb21bddfc830b78f700f0a63595a;p=platform%2Fframework%2Fweb%2Fcrosswalk-tizen.git Merge branch 'master' of https://github.com/MaxWhere/electron into MaxWhere-master --- ee0d48dc5a3beb21bddfc830b78f700f0a63595a diff --cc atom/browser/native_window.cc index f40f7de8d,19120da07..b88c37576 --- a/atom/browser/native_window.cc +++ b/atom/browser/native_window.cc @@@ -38,7 -47,12 +43,8 @@@ #include "ui/gfx/geometry/size.h" #include "ui/gfx/screen.h" #include "ui/gl/gpu_switching_manager.h" + #include "ui/events/event.h" -#if defined(OS_WIN) -#include "ui/gfx/switches.h" -#endif - using content::NavigationEntry; using content::RenderWidgetHostView; using content::RenderWidgetHost; diff --cc docs/api/browser-window.md index 29171a2ec,c338f2470..6a168e9e7 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@@ -242,13 -227,20 +242,22 @@@ Emitted when DevTools is closed ### Event: 'devtools-focused' -Emitted when devtools is focused / opened. +Emitted when DevTools is focused / opened. - ### Event: 'app-command' _Windows_ + ### Event: 'frame-rendered' + + * `event` Event + * `frame` Buffer + * `size` Number + + Emitted when *offscreen render* is enabled, the current frame's pixel data + and size are available. + + ### Event: 'app-command': -Emitted when an [App Command](https://msdn.microsoft.com/en-us/library/windows/desktop/ms646275(v=vs.85).aspx) is invoked. These are typically related to keyboard media keys or browser commands, as well as the "Back" button built into some mice on Windows. +Emitted when an [App Command](https://msdn.microsoft.com/en-us/library/windows/desktop/ms646275(v=vs.85).aspx) +is invoked. These are typically related to keyboard media keys or browser +commands, as well as the "Back" button built into some mice on Windows. ```js someWindow.on('app-command', function(e, cmd) { @@@ -772,3 -732,639 +781,68 @@@ Sets whether the window should be visib Returns whether the window is visible on all workspaces. **Note:** This API always returns false on Windows. + + ### BrowserWindow.beginFrameSubscription() + + Enables offscreen rendering, after this call `frame-rendered` events will be + fired when the window receives a new frame from the renderer. + + ### BrowserWindow.endFrameSubscription() + + Enables offscreen rendering, after this call `frame-rendered` events will + no longer be fired if offscreen rendering was enabled before. + + ### BrowserWindow.sendMouseEvent(options) + + Sends a mouse event to the BrowserWindow. + * `options` Object + * `type` String - The type of the mouse event. + * `down` String - Mouse down event. + * `up` String - Mouse up event. + * `move` String - Mouse move event. + * `enter` String - Mouse enter event. + * `leave` String - Mouse leave event. + * `context-menu` String - Context menu event. + * `wheel` String - Mouse wheel event. + * `x` Integer - The x component of the location of the mouse event. + * `y` Integer - The y component of the location of the mouse event. + * `movement-x` Integer - The x component of the mouse movement since the last event. + * `movement-y` Integer - The y component of the mouse movement since the last event. + * `button` String - The mouse button associated with the mouse event. Also sets the associated modifier values on the event. + * `left` String - The left button was pressed. + * `right` String - The right button was pressed. + * `middle` String - The middle button was pressed. + * `click-count` Integer - The number of clicks associated with the mouse event. + * `precise` Boolean - For the `wheel` event type, this option sets the `hasPreciseScrollingDeltas` option of the event. + * `modifiers` Object - The modifier values associated with the event. + * `left-button-down` Boolean - The left mouse button was pressed. + * `middle-button-down` Boolean - The right mouse button was pressed. + * `right-button-down` Boolean - The middle mouse button was pressed. + * `shift` Boolean - The shift key was pressed. + * `control` Boolean - The control key was pressed. + * `alt` Boolean - The alt key was pressed. + * `meta` Boolean - The meta key was pressed. + * `caps-lock` Boolean - The caps-lock key was on. + * `num-lock` Boolean - The num-lock key was on. + + ### BrowserWindow.sendKeyboardEvent(options) + + Sends a keyboard event to the BrowserWindow. + * `options` Object + * `type` String - The type of the keyboard event. + * `down` String - Key down event. + * `up` String - Key up event. + * `char` String - Character event. + * `code` Integer - The key code of the key that generated the event. + * `native` Integer - The native key code of the key that generated the event. + * `modifiers` Object - The modifier values associated with the event. + * `keypad` Boolean - Sets the `IsKeyPad` option of the event. + * `auto-repeat` Boolean - Sets the `IsAutoRepeat` option of the event. + * `left` Boolean - Sets the `IsLeft` option of the event. + * `right` Boolean - Sets the `IsRight` option of the event. + * `shift` Boolean - The shift key was pressed. + * `control` Boolean - The control key was pressed. + * `alt` Boolean - The alt key was pressed. + * `meta` Boolean - The meta key was pressed. + * `caps-lock` Boolean - The caps-lock key was on. + * `num-lock` Boolean - The num-lock key was on. - -## Class: WebContents - -A `WebContents` is responsible for rendering and controlling a web page. - -`WebContents` is an -[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter). - -### Event: 'did-finish-load' - -Emitted when the navigation is done, i.e. the spinner of the tab will stop -spinning, and the `onload` event was dispatched. - -### Event: 'did-fail-load' - -* `event` Event -* `errorCode` Integer -* `errorDescription` String - -This event is like `did-finish-load`, but emitted when the load failed or was -cancelled, e.g. `window.stop()` is invoked. - -### Event: 'did-frame-finish-load' - -* `event` Event -* `isMainFrame` Boolean - -Emitted when a frame has done navigation. - -### Event: 'did-start-loading' - -Corresponds to the points in time when the spinner of the tab starts spinning. - -### Event: 'did-stop-loading' - -Corresponds to the points in time when the spinner of the tab stops spinning. - -### Event: 'did-get-response-details' - -* `event` Event -* `status` Boolean -* `newUrl` String -* `originalUrl` String -* `httpResponseCode` Integer -* `requestMethod` String -* `referrer` String -* `headers` Object - -Emitted when details regarding a requested resource is available. -`status` indicates the socket connection to download the resource. - -### Event: 'did-get-redirect-request' - -* `event` Event -* `oldUrl` String -* `newUrl` String -* `isMainFrame` Boolean - -Emitted when a redirect was received while requesting a resource. - -### Event: 'dom-ready' - -* `event` Event - -Emitted when document in the given frame is loaded. - -### Event: 'page-favicon-updated' - -* `event` Event -* `favicons` Array - Array of Urls - -Emitted when page receives favicon urls. - -### Event: 'new-window' - -* `event` Event -* `url` String -* `frameName` String -* `disposition` String - Can be `default`, `foreground-tab`, `background-tab`, - `new-window` and `other` - -Emitted when the page requested to open a new window for `url`. It could be -requested by `window.open` or an external link like ``. - -By default a new `BrowserWindow` will be created for the `url`. - -Calling `event.preventDefault()` can prevent creating new windows. - -### Event: 'will-navigate' - -* `event` Event -* `url` String - -Emitted when user or the page wants to start a navigation, it can happen when -`window.location` object is changed or user clicks a link in the page. - -This event will not emit when the navigation is started programmatically with APIs -like `WebContents.loadUrl` and `WebContents.back`. - -Calling `event.preventDefault()` can prevent the navigation. - -### Event: 'crashed' - -Emitted when the renderer process is crashed. - -### Event: 'plugin-crashed' - -* `event` Event -* `name` String -* `version` String - -Emitted when a plugin process is crashed. - -### Event: 'destroyed' - -Emitted when the WebContents is destroyed. - -### WebContents.session - -Returns the `Session` object used by this WebContents. - -### WebContents.loadUrl(url, [options]) - -* `url` URL -* `options` URL - * `httpReferrer` String - A HTTP Referer url - * `userAgent` String - A user agent originating the request - -Loads the `url` in the window, the `url` must contains the protocol prefix, -e.g. the `http://` or `file://`. - -### WebContents.getUrl() - -Returns URL of current web page. - -### WebContents.getTitle() - -Returns the title of web page. - -### WebContents.isLoading() - -Returns whether web page is still loading resources. - -### WebContents.isWaitingForResponse() - -Returns whether web page is waiting for a first-response for the main resource -of the page. - -### WebContents.stop() - -Stops any pending navigation. - -### WebContents.reload() - -Reloads current page. - -### WebContents.reloadIgnoringCache() - -Reloads current page and ignores cache. - -### WebContents.canGoBack() - -Returns whether the web page can go back. - -### WebContents.canGoForward() - -Returns whether the web page can go forward. - -### WebContents.canGoToOffset(offset) - -* `offset` Integer - -Returns whether the web page can go to `offset`. - -### WebContents.clearHistory() - -Clears the navigation history. - -### WebContents.goBack() - -Makes the web page go back. - -### WebContents.goForward() - -Makes the web page go forward. - -### WebContents.goToIndex(index) - -* `index` Integer - -Navigates to the specified absolute index. - -### WebContents.goToOffset(offset) - -* `offset` Integer - -Navigates to the specified offset from the "current entry". - -### WebContents.isCrashed() - -Whether the renderer process has crashed. - -### WebContents.setUserAgent(userAgent) - -* `userAgent` String - -Overrides the user agent for this page. - -### WebContents.getUserAgent() - -Returns a `String` represents the user agent for this page. - -### WebContents.insertCSS(css) - -* `css` String - -Injects CSS into this page. - -### WebContents.executeJavaScript(code[, userGesture]) - -* `code` String -* `userGesture` Boolean - -Evaluates `code` in page. - -In browser some HTML APIs like `requestFullScreen` can only be invoked if it -is started by user gesture, by specifying `userGesture` to `true` developers -can ignore this limitation. - -### WebContents.setAudioMuted(muted) - -+ `muted` Boolean - -Set the page muted. - -### WebContents.isAudioMuted() - -Returns whether this page has been muted. - -### WebContents.undo() - -Executes editing command `undo` in page. - -### WebContents.redo() - -Executes editing command `redo` in page. - -### WebContents.cut() - -Executes editing command `cut` in page. - -### WebContents.copy() - -Executes editing command `copy` in page. - -### WebContents.paste() - -Executes editing command `paste` in page. - -### WebContents.pasteAndMatchStyle() - -Executes editing command `pasteAndMatchStyle` in page. - -### WebContents.delete() - -Executes editing command `delete` in page. - -### WebContents.selectAll() - -Executes editing command `selectAll` in page. - -### WebContents.unselect() - -Executes editing command `unselect` in page. - -### WebContents.replace(text) - -* `text` String - -Executes editing command `replace` in page. - -### WebContents.replaceMisspelling(text) - -* `text` String - -Executes editing command `replaceMisspelling` in page. - -### WebContents.hasServiceWorker(callback) - -* `callback` Function - -Checks if any serviceworker is registered and returns boolean as -response to `callback`. - -### WebContents.unregisterServiceWorker(callback) - -* `callback` Function - -Unregisters any serviceworker if present and returns boolean as -response to `callback` when the JS promise is fullfilled or false -when the JS promise is rejected. - -### WebContents.print([options]) - -* `options` Object - * `silent` Boolean - Don't ask user for print settings, defaults to `false` - * `printBackground` Boolean - Also prints the background color and image of - the web page, defaults to `false`. - -Prints window's web page. When `silent` is set to `false`, Electron will pick -up system's default printer and default settings for printing. - -Calling `window.print()` in web page is equivalent to call -`WebContents.print({silent: false, printBackground: false})`. - -**Note:** On Windows, the print API relies on `pdf.dll`. If your application -doesn't need print feature, you can safely remove `pdf.dll` in saving binary -size. - -### WebContents.printToPDF(options, callback) - -* `options` Object - * `marginsType` Integer - Specify the type of margins to use - * 0 - default - * 1 - none - * 2 - minimum - * `pageSize` String - Specify page size of the generated PDF - * `A4` - * `A3` - * `Legal` - * `Letter` - * `Tabloid` - * `printBackground` Boolean - Whether to print CSS backgrounds. - * `printSelectionOnly` Boolean - Whether to print selection only. - * `landscape` Boolean - `true` for landscape, `false` for portrait. - -* `callback` Function - `function(error, data) {}` - * `error` Error - * `data` Buffer - PDF file content - -Prints windows' web page as PDF with Chromium's preview printing custom -settings. - -By default, an empty `options` will be regarded as -`{marginsType:0, printBackgrounds:false, printSelectionOnly:false, - landscape:false}`. - -```javascript -var BrowserWindow = require('browser-window'); -var fs = require('fs'); - -var win = new BrowserWindow({width: 800, height: 600}); -win.loadUrl("http://github.com"); - -win.webContents.on("did-finish-load", function() { - // Use default printing options - win.webContents.printToPDF({}, function(error, data) { - if (error) throw error; - fs.writeFile("/tmp/print.pdf", data, function(error) { - if (err) - throw error; - console.log("Write PDF successfully."); - }) - }) -}); -``` - -### WebContents.addWorkSpace(path) - -* `path` String - -Adds the specified path to devtools workspace. - -### WebContents.removeWorkSpace(path) - -* `path` String - -Removes the specified path from devtools workspace. - -### WebContents.send(channel[, args...]) - -* `channel` String - -Send `args..` to the web page via `channel` in asynchronous message, the web -page can handle it by listening to the `channel` event of `ipc` module. - -An example of sending messages from the main process to the renderer process: - -```javascript -// On the main process. -var window = null; -app.on('ready', function() { - window = new BrowserWindow({width: 800, height: 600}); - window.loadUrl('file://' + __dirname + '/index.html'); - window.webContents.on('did-finish-load', function() { - window.webContents.send('ping', 'whoooooooh!'); - }); -}); -``` - -```html -// index.html - - - - - -``` - -**Note:** - -1. The IPC message handler in web pages do not have a `event` parameter, which - is different from the handlers on the main process. -2. There is no way to send synchronous messages from the main process to a - renderer process, because it would be very easy to cause dead locks. - -## Class: Session - -### Session.cookies - -The `cookies` gives you ability to query and modify cookies, an example is: - -```javascript -var BrowserWindow = require('browser-window'); - -var win = new BrowserWindow({ width: 800, height: 600 }); - -win.loadUrl('https://github.com'); - -win.webContents.on('did-finish-load', function() { - // Query all cookies. - win.webContents.session.cookies.get({}, function(error, cookies) { - if (error) throw error; - console.log(cookies); - }); - - // Query all cookies that are associated with a specific url. - win.webContents.session.cookies.get({ url : "http://www.github.com" }, - function(error, cookies) { - if (error) throw error; - console.log(cookies); - }); - - // Set a cookie with the given cookie data; - // may overwrite equivalent cookies if they exist. - win.webContents.session.cookies.set( - { url : "http://www.github.com", name : "dummy_name", value : "dummy"}, - function(error, cookies) { - if (error) throw error; - console.log(cookies); - }); -}); -``` - -### Session.cookies.get(details, callback) - -* `details` Object - * `url` String - Retrieves cookies which are associated with `url`. - Empty imples retrieving cookies of all urls. - * `name` String - Filters cookies by name - * `domain` String - Retrieves cookies whose domains match or are subdomains of `domains` - * `path` String - Retrieves cookies whose path matches `path` - * `secure` Boolean - Filters cookies by their Secure property - * `session` Boolean - Filters out session or persistent cookies. -* `callback` Function - function(error, cookies) - * `error` Error - * `cookies` Array - array of `cookie` objects. - * `cookie` - Object - * `name` String - The name of the cookie - * `value` String - The value of the cookie - * `domain` String - The domain of the cookie - * `host_only` String - Whether the cookie is a host-only cookie - * `path` String - The path of the cookie - * `secure` Boolean - Whether the cookie is marked as Secure (typically HTTPS) - * `http_only` Boolean - Whether the cookie is marked as HttpOnly - * `session` Boolean - Whether the cookie is a session cookie or a persistent - cookie with an expiration date. - * `expirationDate` Double - (Option) The expiration date of the cookie as - the number of seconds since the UNIX epoch. Not provided for session cookies. - - -### Session.cookies.set(details, callback) - -* `details` Object - * `url` String - Retrieves cookies which are associated with `url` - * `name` String - The name of the cookie. Empty by default if omitted. - * `value` String - The value of the cookie. Empty by default if omitted. - * `domain` String - The domain of the cookie. Empty by default if omitted. - * `path` String - The path of the cookie. Empty by default if omitted. - * `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to false. - * `session` Boolean - Whether the cookie should be marked as HttpOnly. Defaults to false. - * `expirationDate` Double - The expiration date of the cookie as the number of - seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie. - -* `callback` Function - function(error) - * `error` Error - -### Session.cookies.remove(details, callback) - -* `details` Object - * `url` String - The URL associated with the cookie - * `name` String - The name of cookie to remove -* `callback` Function - function(error) - * `error` Error - -### Session.clearCache(callback) - -* `callback` Function - Called when operation is done - -Clears the session's HTTP cache. - -### Session.clearStorageData([options, ]callback) - -* `options` Object - * `origin` String - Should follow `window.location.origin`'s representation - `scheme://host:port` - * `storages` Array - The types of storages to clear, can contain: - `appcache`, `cookies`, `filesystem`, `indexdb`, `localstorage`, - `shadercache`, `websql`, `serviceworkers` - * `quotas` Array - The types of quotas to clear, can contain: - `temporary`, `persistent`, `syncable` -* `callback` Function - Called when operation is done - -Clears the data of web storages. - -### Session.setProxy(config, callback) - -* `config` String -* `callback` Function - Called when operation is done - -Parses the `config` indicating which proxies to use for the session. - -``` -config = scheme-proxies[";"] -scheme-proxies = ["="] -url-scheme = "http" | "https" | "ftp" | "socks" -proxy-uri-list = [","] -proxy-uri = ["://"][":"] - - For example: - "http=foopy:80;ftp=foopy2" -- use HTTP proxy "foopy:80" for http:// - URLs, and HTTP proxy "foopy2:80" for - ftp:// URLs. - "foopy:80" -- use HTTP proxy "foopy:80" for all URLs. - "foopy:80,bar,direct://" -- use HTTP proxy "foopy:80" for all URLs, - failing over to "bar" if "foopy:80" is - unavailable, and after that using no - proxy. - "socks4://foopy" -- use SOCKS v4 proxy "foopy:1080" for all - URLs. - "http=foopy,socks5://bar.com -- use HTTP proxy "foopy" for http URLs, - and fail over to the SOCKS5 proxy - "bar.com" if "foopy" is unavailable. - "http=foopy,direct:// -- use HTTP proxy "foopy" for http URLs, - and use no proxy if "foopy" is - unavailable. - "http=foopy;socks=foopy2 -- use HTTP proxy "foopy" for http URLs, - and use socks4://foopy2 for all other - URLs. -``` - -### Session.setDownloadPath(path) - -* `path` String - The download location - -Sets download saving directory. By default, the download directory will be the -`Downloads` under the respective app folder.