mozilla

Revision 485853 of HelperApps.jsm

  • Revision slug: Extensions/Mobile/API/HelperApps.jsm
  • Revision title: HelperApps.jsm
  • Revision id: 485853
  • 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, promptOptions, callback)
Parameters
apps
A list of App objects that should be shown in the prompt
promptOptions

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"));
HelperApps.prompt(apps, {
  title: "Pick!",
  buttons: ["OK"]
}, function(result) {
  alert(apps[result.icongrid0].name);
});

getAppsForProtocol()

Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.

Prompt addButton(aOptions);
Parameters

Takes an object with parameters describing the button

Parameter Description
label The label to show on the button.
Return value

Returns the Prompt that is being modified.

Example
var p = new Prompt({
  window: window,
  title: "My Prompt",
  message: "A message on the prompt"
});

if (shouldShowButtons) {
  p.addButton({ label: "Button 1" });
  p.addButton({ label: "Button 2" });
}

p.show(function(data) {
  if (data.button == 0)
    alert("Clicked button 1!");
  else if (data.button == 1)
    alert("Clicked button 2!");
});

addButton()

Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.

Prompt addButton(aOptions);
Parameters

Takes an object with parameters describing the button

Parameter Description
label The label to show on the button.
Return value

Returns the Prompt that is being modified.

Example
var p = new Prompt({
  window: window,
  title: "My Prompt",
  message: "A message on the prompt"
});

if (shouldShowButtons) {
  p.addButton({ label: "Button 1" });
  p.addButton({ label: "Button 2" });
}

p.show(function(data) {
  if (data.button == 0)
    alert("Clicked button 1!");
  else if (data.button == 1)
    alert("Clicked button 2!");
});

addButton()

Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.

Prompt addButton(aOptions);
Parameters

Takes an object with parameters describing the button

Parameter Description
label The label to show on the button.
Return value

Returns the Prompt that is being modified.

Example
var p = new Prompt({
  window: window,
  title: "My Prompt",
  message: "A message on the prompt"
});

if (shouldShowButtons) {
  p.addButton({ label: "Button 1" });
  p.addButton({ label: "Button 2" });
}

p.show(function(data) {
  if (data.button == 0)
    alert("Clicked button 1!");
  else if (data.button == 1)
    alert("Clicked button 2!");
});

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, promptOptions, 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>promptOptions</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"));
HelperApps.prompt(apps, {
  title: "Pick!",
  buttons: ["OK"]
}, function(result) {
  alert(apps[result.icongrid0].name);
});
</pre>
<h3 id="getAppsForProtocol" name="getAppsForProtocol">getAppsForProtocol()</h3>
<p>Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.</p>
<pre class="eval">
Prompt addButton(aOptions);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<p>Takes an object with parameters describing the button</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>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>Returns the Prompt that is being modified.</p>
<h6 id="Example" name="Example">Example</h6>
<pre>
var p = new Prompt({
  window: window,
  title: "My Prompt",
  message: "A message on the prompt"
});

if (shouldShowButtons) {
  p.addButton({ label: "Button 1" });
  p.addButton({ label: "Button 2" });
}

p.show(function(data) {
  if (data.button == 0)
    alert("Clicked button 1!");
  else if (data.button == 1)
    alert("Clicked button 2!");
});
</pre>
<h3 id="addButton" name="addButton">addButton()</h3>
<p>Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.</p>
<pre class="eval">
Prompt addButton(aOptions);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<p>Takes an object with parameters describing the button</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>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>Returns the Prompt that is being modified.</p>
<h6 id="Example" name="Example">Example</h6>
<pre>
var p = new Prompt({
  window: window,
  title: "My Prompt",
  message: "A message on the prompt"
});

if (shouldShowButtons) {
  p.addButton({ label: "Button 1" });
  p.addButton({ label: "Button 2" });
}

p.show(function(data) {
  if (data.button == 0)
    alert("Clicked button 1!");
  else if (data.button == 1)
    alert("Clicked button 2!");
});
</pre>
<h3 id="addButton" name="addButton">addButton()</h3>
<p>Adds a button to the prompt. A maximum of three buttons can be shown at the dialog at any time. If there are already three buttons present, this will silently fail.</p>
<pre class="eval">
Prompt addButton(aOptions);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<p>Takes an object with parameters describing the button</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>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>Returns the Prompt that is being modified.</p>
<h6 id="Example" name="Example">Example</h6>
<pre>
var p = new Prompt({
  window: window,
  title: "My Prompt",
  message: "A message on the prompt"
});

if (shouldShowButtons) {
  p.addButton({ label: "Button 1" });
  p.addButton({ label: "Button 2" });
}

p.show(function(data) {
  if (data.button == 0)
    alert("Clicked button 1!");
  else if (data.button == 1)
    alert("Clicked button 2!");
});
</pre>
Revert to this revision