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])
    Object extractMetaData(blob)
    Object getDragData(event, flavor)
    void openFiles(callback, [options])
    void setDropEffect(event, dropEffect)
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. Note that for technical reasons, on Windows Mobile, any query parameters are stripped from the URL.
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.

Any query in the shortcut URL must not contain literal percent symbols, encoded (%25) or otherwise. Any such characters will be stripped from the URL.
extractMetaData(blob)
Summary: Calculates metadata (such as MIME type) from a Blob's contents. For example, if the Blob contains image data in a well-known encoding (such as PNG or JPEG), this will return the image's width and height.
Parameters: blob - The Blob to examine.
Return value: A JavaScript Object (i.e. a key-value map). Currently, four keys are provided (although all keys are optional -- no key is guaranteed to be present on all Blobs):
  • "mimeType", which can have values such as "image/jpeg", "image/png", or "application/octet-stream".
  • "imageWidth", only defined for Blobs that contain image data, will have an integer value that is the width of that image.
  • "imageHeight" is similar to "imageWidth".
  • "exifOrientation", only defined for Blobs that contain JPEG image data that have Exif metadata. The value is an integer between 1 and 8 (inclusive), as per the Exif 2.2 specification (section 4.6.4.A under "Orientation").
getDragData(event, flavor)
Summary: Returns the data that is on the OS's drag-and-drop clipboard. This method is valid to call only during processing of a drag-and-drop event (such as during ondragenter, ondragover, ondragleave or ondrop). This method is analogous to HTML5's DataTransfer.getData method.
Parameters: event - The drag-and-drop event. Typically, just pass window.event. On Firefox, pass the event that is given as an argument of the event handler.
flavor - The flavor of data requested. Currently, the only supported flavor is "application/x-gears-files", to get File data.
Return value: A JavaScript Object (i.e. a key-value map). One such key is "count", which is the number of objects being dragged. Another key, only present during an ondrop event and not other events, is "files", which will return the actual File objects being drag-and-dropped.
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.
setDropEffect(event, dropEffect)
Summary: Sets the dropEffect (i.e. the cursor) in response to a drag-and-drop event. This method is valid to call only during processing of a drag-and-drop event (such as during ondragenter, ondragover, ondragleave or ondrop). This method is analogous to HTML5's DataTransfer.dropEffect setter.
Parameters: event - The drag-and-drop event. Typically, just pass window.event. On Firefox, pass the event that is given as an argument of the event handler.
dropEffect - Either the value "copy", or "none".

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', 'text/plain', '.mov']

Partial content types like 'image/*' are not currently supported.

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.