The Desktop module provides an interface for accessing desktop related functionality, such as creating shortcuts.
Does not require user permission.
<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>
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
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):
|
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".
|
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.
|
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. |
Attribute | Type | Description |
---|---|---|
name | readonly string | The name of the file, excluding the path. |
blob | readonly Blob | The contents of the file. |