English | Site Directory

Desktop API

The Desktop module provides an interface for accessing desktop related functionality, such as creating shortcuts.

Permission

Does not require user permission.

Example

<script type="text/javascript" src="gears_init.js"></script>
<script type="text/javascript">
var desktop = google.gears.factory.create('beta.desktop');

desktop.createShortcut('Test Application',
                       'http://example.com/index.html',
                       {'128x128': 'http://example.com/icon128x128.png',
                          '48x48': 'http://example.com/icon48x48.png',
                          '32x32': 'http://example.com/icon32x32.png',
                          '16x16': 'http://example.com/icon16x16.png'},
                       'An application at http://example.com/index.html');

function openFilesCallback(files) {
  alert('User selected ' + files.length + ' files.');
}
desktop.openFiles(openFilesCallback);
</script>

Interfaces

Desktop class
    void createShortcut(name, url, icons, [description])
    void openFiles(callback, [options])
OpenFilesCallback(File[] files)
OpenFileOptions class
    attribute bool singleFile
    attribute string[] filter
File class
    readonly attribute string name
    readonly attribute Blob blob

Desktop class

Methods

createShortcut(name, url, icons, [description])
Summary: Creates a desktop shortcut for launching a web application.
Parameters: name - The user-visible name of the shortcut. It cannot contain any of these characters: "\/:*?<>|
url - The address to launch when the user opens the shortcut. The URL must be in the same origin as the calling page.
icons - An object containing one or more of these named properties: 128x128, 48x48, 32x32, 16x16. The value of each property must be the URL of a PNG-formatted image with dimensions matching the property name. A data URL containing base64-encoded PNG data can also be used.
description - Optional. Additional text to display in the confirmation dialog.
Details: The icon sizes were chosen to meet the needs of a variety of platforms. If an application wants its icons to look as good as possible on all platforms, it should provide all valid sizes.

The shortcut will launch the same web browser that created the shortcut.

The url and icons values can be relative or absolute URLs. Relative URLs are resolved using the caller's location.

Calling this API will trigger a confirmation dialog. The dialog will use the 32x32 icon if it exists, or else the closest size available.

Users can choose to never allow a particular named shortcut for a given origin, in which case the dialog will not be displayed.

Shortcuts created through this API cannot overwrite an existing shortcut with the same name, and such attempts fail silently. This restriction may be relaxed in a future version of Gears.
openFiles(callback, [options])
Summary: Provides user-driven access to files on the client machine. Presents the user with a file selection dialog for choosing files to make available to the application.
Parameters: callback - After the user has selected files, this function is invoked with an array of the files that were selected. This function must conform to the OpenFilesCallback interface.

options - An optional parameter of type OpenFileOptions. Provides control over file selection options.
Details: The openFiles call will immediately return after presenting a file selection dialog to the user. It does not wait for the user to select files, nor does it wait for the dialog to be closed.

Once the user has selected files, the callback is invoked with an array of the files which were selected.

If the user cancels the dialog without selecting any files, the callback is invoked with an empty array.

OpenFilesCallback interface

void OpenFilesCallback(File[] files)
Summary: A method matching this signature should be passed as the first argument to openFiles. It will be invoked with an array of the files which were selected.
Parameters: files - An array containing the files that have been selected. If the user dismisses the file selection dialog without choosing any files, this array will be empty.

OpenFileOptions class

Attributes

Attribute Type Description
singleFile bool By default, the user may select multiple files. If true, the user is limited to selecting only one file.
filter string[] By default, all files on the local disk are selectable. If a filter is provided, only files matching the filter are selectable. The user can turn the filter off, so be aware that selected files may not match the filter. The filter is an array of Internet content types and/or file extensions. Example: ['text/html', '.txt', 'image/*']

File class

Attributes

Attribute Type Description
name readonly string The name of the file, excluding the path.
blob readonly Blob The contents of the file.