Revision 501281 of HelperApps.jsm

  • Revision slug: Mozilla/Add-ons/Firefox_for_Android/API/HelperApps.jsm
  • Revision title: HelperApps.jsm
  • Revision id: 501281
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment Extensions/Mobile/API/HelperApps.jsm Mozilla/Add-ons/Firefox_for_Android/API/HelperApps.jsm

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();
  });
}

Property overview

App

App.name
App.isDefault
App.packageName
App.iconUri

Method overview

App

App.launch(nsIURI uri);

HelperApps

HelperApps.showPicker(App[] apps, Object promptOptions, Function callback)
HelperApps.getAppsForProtocol(String scheme)
HelperApps.getAppsForUri(nsIURI uri, Object flags = { filterHttp: true })
HelperApps.launchUri(nsIURI uri)

Methods

App.launch()

Launches an app with an nsIURI. This attempts to use an Implicit Android intent, and will not show an intent chooser.

void launch(nsIURI uri);

Parameters

uri
The nsIURI to launch

Example

let uri = Services.io.newUri("http://www.mozilla.org", null, null);
let apps = HelperApps.getAppsForUri(uri);
apps[0].launch(uri);

HelperApps.showPicker()

Uses 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.jsm constructor.

Parameter Description
window The window that is opening this prompt. {{ optional_inline() }}
title The title to show on the prompt. {{ optional_inline() }}
message A message to show on the prompt. {{ optional_inline() }}
buttons An array of Strings to show as buttons on the prompt. Prompts on Android support a maximum of three buttons. Any more will be ignored. {{ optional_inline() }}
callback
A function to be called when the prompt returns. Similar to the callback called from Prompt.show().

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);
});

HelperApps.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);

HelperApps.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 to use when filtering. Defaults to Intent.ACTION_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 nsIURI. 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);

HelperApps.launchUri()

Sends an nsIURI 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(nsIURI uri);

Parameters

Takes an nsIURI to launch.

Return value

None

Example

HelperApps.launchUri(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">Property overview</h2>
<h4 id="App">App</h4>
<table class="standard-table">
 <tbody>
  <tr>
   <td>App.name</td>
  </tr>
  <tr>
   <td>App.isDefault</td>
  </tr>
  <tr>
   <td>App.packageName</td>
  </tr>
  <tr>
   <td>App.iconUri</td>
  </tr>
 </tbody>
</table>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<h4 id="App">App</h4>
<table class="standard-table">
 <tbody>
  <tr>
   <td>App.launch(<a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> uri);</td>
  </tr>
 </tbody>
</table>
<h4 id="HelperApps">HelperApps</h4>
<table class="standard-table">
 <tbody>
  <tr>
   <td>HelperApps.showPicker(App[] apps, Object promptOptions, Function callback)</td>
  </tr>
  <tr>
   <td>HelperApps.getAppsForProtocol(String scheme)</td>
  </tr>
  <tr>
   <td>HelperApps.getAppsForUri(<a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> uri, Object flags = { filterHttp: true })</td>
  </tr>
  <tr>
   <td>HelperApps.launchUri(<a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> uri)</td>
  </tr>
 </tbody>
</table>
<h2 id="Methods" name="Methods">Methods</h2>
<h3 id="showPicker" name="showPicker">App.launch()</h3>
<p>Launches an app with an <a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a>. This attempts to use an <a href="https://developer.android.com/guide/components/intents-filters.html#ires">Implicit Android intent</a>, and will not show an intent chooser.</p>
<pre class="eval">
void launch(<a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> uri);
</pre>
<h4 id="Parameters" name="Parameters">Parameters</h4>
<dl>
 <dt>
  uri</dt>
 <dd>
  The <a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> to launch</dd>
</dl>
<h4 id="Example" name="Example">Example</h4>
<pre>
let uri = Services.io.newUri("http://www.mozilla.org", null, null);
let apps = HelperApps.getAppsForUri(uri);
apps[0].launch(uri);
</pre>
<h3 id="showPicker" name="showPicker">HelperApps.showPicker()</h3>
<p>Uses <a href="/en-US/docs/Extensions/Mobile/API/Prompt.jsm">Prompt.jsm</a> to show a prompt asking users which app they want to launch</p>
<pre class="eval">
void showPicker(apps, options, callback)
</pre>
<h4 id="Parameters" name="Parameters">Parameters</h4>
<dl>
 <dt>
  apps</dt>
 <dd>
  A list of App objects that should be shown in the prompt</dd>
 <dt>
  options</dt>
 <dd>
  <p>An <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">object</a> describing the dialog to be shown, commonly used to add a title/buttons. The same type of object that can be passed to a <a href="/en-US/docs/">Prompt.jsm</a> constructor.</p>
  <table class="standard-table">
   <tbody>
    <tr>
     <td class="header">Parameter</td>
     <td class="header">Description</td>
    </tr>
    <tr>
     <td><code>window</code></td>
     <td>The window that is opening this prompt. {{ optional_inline() }}</td>
    </tr>
    <tr>
     <td><code>title</code></td>
     <td>The title to show on the prompt. {{ optional_inline() }}</td>
    </tr>
    <tr>
     <td><code>message</code></td>
     <td>A message to show on the prompt. {{ optional_inline() }}</td>
    </tr>
    <tr>
     <td><code>buttons</code></td>
     <td>An array of Strings to show as buttons on the prompt. Prompts on Android support a maximum of three buttons. Any more will be ignored. {{ optional_inline() }}</td>
    </tr>
   </tbody>
  </table>
 </dd>
 <dt>
  callback</dt>
 <dd>
  A <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">function</a> to be called when the prompt returns. Similar to the callback called from <a href="https://developer.mozilla.org/en-US/docs/Extensions/Mobile/API/Prompt.jsm#show">Prompt.show()</a>.</dd>
</dl>
<h4 id="Example" name="Example">Example</h4>
<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">HelperApps.getAppsForProtocol()</h3>
<p>Get an array of App objects that can handle this protocol.</p>
<pre class="eval">
App[] getAppsForProtocol(protocol);
</pre>
<h4 id="Parameters" name="Parameters">Parameters</h4>
<p>Takes a string protocol</p>
<h4 id="Return_value" name="Return_value">Return value</h4>
<p>Returns an array of App objects. Array will be length zero if none are found.</p>
<h4 id="Example" name="Example">Example</h4>
<pre>
let httpHandlers = getAppsForProtocol("http");
alert("Http links can be opened with " + httpHandlers[0].name);
</pre>
<h3 id="getAppsForUri" name="getAppsForUri">HelperApps.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>
<h4 id="Parameters" name="Parameters">Parameters</h4>
<dl>
 <dt>
  uri</dt>
 <dd>
  The nsIUri of the page</dd>
 <dt>
  flags</dt>
 <dd>
  A set of flags to control the filter</dd>
</dl>
<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 <a href="http://developer.android.com/reference/android/content/Intent.html">Android Intent</a> <a href="http://developer.android.com/reference/android/content/Intent.html">action</a> to use when filtering. Defaults to <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_VIEW">Intent.ACTION_VIEW</a></td>
  </tr>
  <tr>
   <td><code>packageName</code></td>
   <td>The <a href="http://developer.android.com/guide/topics/manifest/manifest-element.html#package">Android packageName</a> 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 <a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a>. 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>
<h4 id="Return_value" name="Return_value">Return value</h4>
<p>Returns a list of App objects that are registered to open a particular uri</p>
<h4 id="Example" name="Example">Example</h4>
<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">HelperApps.launchUri()</h3>
<p>Sends an <a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> 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(<a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> uri);
</pre>
<h4 id="Parameters" name="Parameters">Parameters</h4>
<p>Takes an <a href="/en-US/docs/XPCOM_Interface_Reference/nsIURI">nsIURI</a> to launch.</p>
<h4 id="Return_value" name="Return_value">Return value</h4>
<p>None</p>
<h4 id="Example" name="Example">Example</h4>
<pre>
HelperApps.launchUri(Services.io.newUri("http://www.google.com", null, null));
</pre>
Revert to this revision