Revision 485859 of HelperApps.jsm

  • Revision slug: Extensions/Mobile/API/HelperApps.jsm
  • Revision title: HelperApps.jsm
  • Revision id: 485859
  • Created:
  • Creator: wesj
  • Is current revision? No
  • Comment

Revision Content

{{MobileOnlyHeader(27.0)}}

{{note("HelperApps.jsm is still under development. The API may change. Use with care!")}}

The HelperApps.jsm JavaScript code module offers utility methods for finding and sending data to other apps installed on the device.

Components.utils.import("resource://gre/modules/HelperApps.jsm");

Basic usage

HelperApps.jsm exports two symbols:

  1. a HelperApps object and
  2. an App constructor into their scope

Example:

let apps = HelperApps.getAppsForUri(uri);

let app = new App({
  name: "My option",
  iconUri: "resource://download";
};
app.launch = function() { apps[1].launch(uri); }
apps.push(app);

if (apps.length > 1) {
  HelperApps.prompt(apps, {
    title:"Launch!",
    buttons: ["OK", "Cancel"]
  }, function(result) {
    var index = result.button == 0 ? result.icongrid0 : undefined;
    if (index != undefined) apps[index].launch();
  });
}

Method overview

showPicker(apps, promptOptions, callback)
getAppsForProtocol(scheme)
getAppsForUri(uri, flags = { filterHttp: true })
launchUri(uri)

Methods

showPicker()

Use Prompt.jsm to show a prompt asking users which app they want to launch

void showPicker(apps, options, callback)
Parameters
apps
A list of App objects that should be shown in the prompt
options

An object describing the dialog to be shown, commonly used to add a title/buttons. The same type of object that can be passed to a Prompt constructor.

Parameter Description
label The label to show on the button.
callback
A function to be called when the prompt returns. Similar to the callback called from Prompt.jsm prompts.
Example
let apps = HelperApps.getAppsForUri(Services.io.newUri("http://www.mozilla.org", null, null)));
HelperApps.prompt(apps, {
  title: "Pick!",
  buttons: ["OK"]
}, function(result) {
  alert(apps[result.icongrid0].name);
});

getAppsForProtocol()

Get an array of App objects that can handle this protocol.

App[] getAppsForProtocol(protocol);
Parameters

Takes a string protocol

Return value

Returns an array of App objects. Array will be length zero if none are found.

Example
let httpHandlers = getAppsForProtocol("http");
alert("Http links can be opened with " + httpHandlers[0].name);

getAppsForUri()

Gets a list of App objects that are registered to open a particular uri

App[] getAppsForUri(uri, flags = { filterHttp: true })
Parameters
uri
The nsIUri of the page
flags
A set of flags to control the filter
Flag Description
filterHttp Should http handlers be filtered from the results. Defaults to true
action The Android Intent action type to use when filtering. Defaults to Intent.VIEW
packageName The Android packageName to use when filtering. Use if you want to find a particular app.
mimeType The mimetype of the uri. If not provided, the implementation will try to guess a mimetype from the URI. If this is overridden, you don't even have to provide a uri to search for, and can instead search for handlers of a particular mimetype.
Return value

Returns a list of App objects that are registered to open a particular uri

Example
let url = "http://www.foo.com/myfile.dat";
let apps = HelperApps.getAppsForUri(Services.io.newUri(url, null, null), { mimeType: "foo/bar" });
alert(url + " can be opened with " + httpHandlers[0].name);

launchUri()

Sends a uri as an intent to the Android system. This may show an Android native Intent chooser if multiple apps are available (and none are marked as default).

void launchUri(uri);
Parameters

Takes an nsIURI to launch.

Return value

None

Example
HelperApps.launch(Services.io.newUri("http://www.google.com", null, null));

Revision Source

<p><code>{{MobileOnlyHeader(27.0)}}</code></p>
<p><code>{{note("HelperApps.jsm is still under development. The API may change. Use with care!")}}</code></p>
<p>The <code>HelperApps.jsm</code> JavaScript code module offers utility methods for finding and sending data to other apps installed on the device.</p>
<pre>
Components.utils.import("resource://gre/modules/<code>HelperApps</code>.jsm");
</pre>
<h2 id="Basic_usage" name="Basic_usage">Basic usage</h2>
<p>HelperApps.jsm exports two symbols:</p>
<ol>
 <li>a HelperApps object and</li>
 <li>an App constructor into their scope</li>
</ol>
<p>Example:</p>
<pre>
let apps = HelperApps.getAppsForUri(uri);

let app = new App({
  name: "My option",
  iconUri: "resource://download";
};
app.launch = function() { apps[1].launch(uri); }
apps.push(app);

if (apps.length &gt; 1) {
  HelperApps.prompt(apps, {
    title:"Launch!",
    buttons: ["OK", "Cancel"]
  }, function(result) {
    var index = result.button == 0 ? result.icongrid0 : undefined;
    if (index != undefined) apps[index].launch();
  });
}
</pre>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<table class="standard-table">
 <tbody>
  <tr>
    <td>showPicker(apps, promptOptions, callback)</td>
  </tr>
  <tr>
    <td>getAppsForProtocol(scheme)</td>
  </tr>
  <tr>
    <td>getAppsForUri(uri, flags = { filterHttp: true })</td>
  </tr>
  <tr>
    <td>launchUri(uri)</td>
  </tr>
 </tbody>
</table>

<h2 id="Methods" name="Methods">Methods</h2>
<h3 id="showPicker" name="showPicker">showPicker()</h3>
<p>Use Prompt.jsm to show a prompt asking users which app they want to launch</p>
<pre class="eval">
void showPicker(apps, options, callback)
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>apps</dt>
  <dd>A list of App objects that should be shown in the prompt</dd>

  <dt>options</dt>
  <dd><p>An object describing the dialog to be shown, commonly used to add a title/buttons. The same type of object that can be passed to a Prompt constructor.</p>
<table class="standard-table">
 <tbody>
  <tr>
   <td class="header">Parameter</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>label</code></td>
   <td>The label to show on the button.</td>
  </tr>
 </tbody>
</table>
</dd>

   <dt>callback</dt>
   <dd>A function to be called when the prompt returns. Similar to the callback called from Prompt.jsm prompts.</dd>
</dl>
<h6 id="Example" name="Example">Example</h6>
<pre>
let apps = HelperApps.getAppsForUri(Services.io.newUri("http://www.mozilla.org", null, null)));
HelperApps.prompt(apps, {
  title: "Pick!",
  buttons: ["OK"]
}, function(result) {
  alert(apps[result.icongrid0].name);
});
</pre>

<h3 id="getAppsForProtocol" name="getAppsForProtocol">getAppsForProtocol()</h3>
<p>Get an array of App objects that can handle this protocol.</p>
<pre class="eval">
App[] getAppsForProtocol(protocol);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<p>Takes a string protocol</p>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>Returns an array of App objects. Array will be length zero if none are found.</p>
<h6 id="Example" name="Example">Example</h6>
<pre>
let httpHandlers = getAppsForProtocol("http");
alert("Http links can be opened with " + httpHandlers[0].name);
</pre>

<h3 id="getAppsForUri" name="getAppsForUri">getAppsForUri()</h3>
<p>Gets a list of App objects that are registered to open a particular uri</p>
<pre class="eval">
App[] getAppsForUri(uri, flags = { filterHttp: true })
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>uri</dt>
  <dd>The nsIUri of the page</dd>
  <dt>flags</dt>
  <dd>A set of flags to control the filter
<table class="standard-table">
 <tbody>
  <tr>
   <td class="header">Flag</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>filterHttp</code></td>
   <td>Should http handlers be filtered from the results. Defaults to true</td>
  </tr>
  <tr>
   <td><code>action</code></td>
   <td>The Android Intent action type to use when filtering. Defaults to Intent.VIEW</td>
  </tr>
  <tr>
   <td><code>packageName</code></td>
   <td>The Android packageName to use when filtering. Use if you want to find a particular app.</td>
  </tr>
  <tr>
   <td><code>mimeType<code></td>
   <td>The mimetype of the uri. If not provided, the implementation will try to guess a mimetype from the URI. If this is overridden, you don't even have to provide a uri to search for, and can instead search for handlers of a particular mimetype.</td>
  </tr>
 </tbody>
</table>
  </dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>Returns a list of App objects that are registered to open a particular uri</p>
<h6 id="Example" name="Example">Example</h6>
<pre>
let url = "http://www.foo.com/myfile.dat";
let apps = HelperApps.getAppsForUri(Services.io.newUri(url, null, null), { mimeType: "foo/bar" });
alert(url + " can be opened with " + httpHandlers[0].name);
</pre>

<h3 id="launchUri" name="launchUri">launchUri()</h3>
<p>Sends a uri as an intent to the Android system. This may show an Android native Intent chooser if multiple apps are available (and none are marked as default).</p>
<pre class="eval">
void launchUri(uri);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<p>Takes an nsIURI to launch.</p>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>None</p>
<h6 id="Example" name="Example">Example</h6>
<pre>
HelperApps.launch(Services.io.newUri("http://www.google.com", null, null));
</pre>
Revert to this revision