Launching another application from your application

You can make your own application automatically launch another application when the user taps on an item, such as a phone number, e-mail, or web link. To enable your application to trigger another application, use certain URI schemes or MIME types associated with file types.

Examples

• When you tap the " http://developer.nokia.com/swipe/" link, the page opens in the web browser.
• When you tap the "mailto:foo@bar.com" address, the email editor opens with the prefilled recipient address.

The URI schemes and MIME type associations are dynamic data in the system: installed applications can register new URI schemes and declare themselves as handlers of certain MIME types. You can define the URI schemes and MIME type associations in the .desktop files of the application.

Note: Desktop files for Harmattan applications are named <project name>_harmattan.desktop, and for Fremantle applications they are named <project name>.desktop.

There can be more than one application capable of handling the same type of data. In that case, either the default application is launched or the user is asked to select which application to open. Therefore, when you use URI schemes and MIME type associations to launch other applications, do not assume that the same application is launched every time and in every case. For example, one user can have several applications capable of playing audio files whereas another user just uses the built-in music player application. When you trigger an action, you ask the system to open the best available application for a certain type of data. However, you cannot control what happens after that or if an application is actually found and launched.

APIs for using URI schemes and MIME types

The MeeGo 1.2 Harmattan platform offers the following libraries for triggering actions based on URI schemes and MIME types:

• QML: Qt.openUrlExternally(url)

  The Qt object is a global object with utility functions, properties and enums. It is always available when you import Qt Quick 1.0 (or a later version). For more information on this method, see Qt documentation.

• QtGui: This library includes the QDesktopServices::openUrl method.

  QDesktopServices::openUrl is a standard method of Qt 4.7. This is the recommended method in most cases, especially if you are looking for a standard solution that is also available on other platforms. For more information on this method, see the QDesktopServices in the MeeGo 1.2 Harmattan API reference library.

• libcontentaction: This library includes the ContentAction::Action class.

  ContentAction::Action provides a similar functionality as QDesktopServices::openUrl method. The libcontentaction library also allows you to highlight URIs in shown texts for applications based on MeeGo Touch. For more information on this library and how URI schemes and MIME type associations work on Harmattan, see the libcontentaction library in the Platform API reference.

Common URI schemes

The following table presents some common URI schemes that work on any Harmattan device. However, as the URI schemes available in the system are dynamic data, applications can add new types of URIs, and multiple applications can handle the same type of URIs. Thus, the table does not provide a complete list of the available URI schemes.

Common URI schemes

URI scheme	Example	Assumed action
http://<...> (also https:, ftp:)	http://developer.nokia.com	Opens the address with the web browser.
file:///<path>	file:///home/user/MyDocs/Pictures/picture.jpg	Opens the file in an application that handles such file types.
mailto:<address>[?<header1>=<value1>[&<header2>=<value2>]]	mailto:foo@bar.com?subject=Subject%20text	Opens the email editor.
tel:<phonenbr>	tel:1234567	Shows a contact card with the phone number. The user can choose to make a call, send an SMS or create a new contact.
geo:<lat>,<lon>	geo:61.446943,23.86449	Shows the location in the Maps application.

Examples of triggering actions

The following section gives examples of triggering actions in your application with the available API libraries.

Example of using QML

To trigger the launch action when the user taps on a link in a text label, do the following:

import QtQuick 1.1
import com.nokia.meego 1.0

Label {
         text: qsTr("Read the Harmattan developer library at<ahref=\"http://harmattan-dev.nokia.com/docs/library\">http://harmattan-dev.nokia.com/docs/library</a>.")
         onLinkActivated: {
                 Qt.openUrlExternally(link)
         }
}

For more information on the onLinkActivated signal, see the QML Text element documentation.

Example of using QDesktopServices

To trigger the launch action with QDesktopServices, add the following line anywhere in your application:

 #include <QDesktopServices>
 #include <QUrl>
 
 // ...
 QDesktopServices::openUrl(QUrl("http://developer.nokia.com"));

Example of using libcontentaction

To trigger the default launch action with libcontentaction, add the following to your application:

 #include <contentaction/contentaction.h>
 
 // ... 
 ContentAction::Action::defaultActionForScheme(QString("http://developer.nokia.com")).trigger();

The libcontentaction library and its ContentAction::Action class also provide other methods. You can use them if you need more fine-grained control on which action to launch and when. For more information, see the libcontentaction library in the Platform API reference.

Additionally, you need to add libcontentaction to the list of libraries to be linked with in the .pro file of your application:

 LIBS += -lcontentaction

Launching your application based on MIME types and URI schemes

You can also declare your own application as the handler of a certain MIME type. For example, to declare your own image viewer as the handler of JPEG and PNG image files, include the following lines in the <project name>_harmattan.desktop file of your application:

 [Desktop Entry]
 # ... 
 Exec=/usr/bin/myimgview %U
 MimeType=image/jpeg;image/png;

The Exec line defines the command line of your application, %U is replaced by the name of the file. The second line defines the MIME type associations for your application.

For more information on defining possible URI schemes for your application, see the libcontentaction library in the Platform API reference.

Using D-Bus to launch applications

D-Bus is a powerful and versatile interface that gives you additional ways to launch other applications, sometimes in a more direct manner. For example, when setting up a phone call, D-Bus allows your application to launch the device phone Call UI directly instead of displaying the contact card like the tel:<phonenbr> URI scheme does. D-Bus is used with the QDBus module in Qt.

The following code snippets demonstrate one possible way to create a class to handle a D-Bus call that launches the device native Call UI during runtime. The class is called DBusMethodProxy and the class file dbusmethodproxy.

The class header file:

#ifndef DBUSMETHODPROXY_H
#define DBUSMETHODPROXY_H

#include <QObject>

class DBusMethodProxy : public QObject
{
    Q_OBJECT
public:
    explicit DBusMethodProxy(QObject *parent = 0); 

signals:

public slots:
    void call(const QString &number);
};
#endif // DBUSMETHODPROXY_H

The class source file:

#include <QDebug>
#include <QDBusMessage>
#include <QDBusConnection>
#include "dbusmethodproxy.h" 

DBusMethodProxy::DBusMethodProxy(QObject *parent) : QObject(parent)
{
}

void DBusMethodProxy::call(const QString &number)
{
   qDebug() << "Number to call:" << number;

   QDBusMessage message = QDBusMessage::createMethodCall(
       "com.nokia.telephony.callhistory",
       "/callhistory",
       "com.nokia.telephony.callhistory",
       "dialer");

   QList<QVariant> args;
   args.append(QVariant(number));
   message.setArguments(args);

   QDBusConnection bus = QDBusConnection::sessionBus();

   if (bus.isConnected())
   {
       bus.send(message);
   }
   else
   {
       qDebug() << "Could not connect to dbus!";
   }
}

The class sends a D-Bus message to the com.nokia.telephony.callhistory interface. The message is sent with the QDBusConnection::send function. This launches the Call UI interface, which the device user can use to make phone calls.

You can further refine this example by making it QML-compatible. To do this, register the DBusMethodProxy class in the main.cpp file.

#include "dbusmethodproxy.h"

int main(int argc, char *argv[])
{
   QApplication app(argc, argv);
   qmlRegisterType<DBusMethodProxy>("LaunchActions", 1, 0, "DBusMethodProxy");
}

You can then easily create the application UI. For example, the following QML snippet creates a TextField for entering a phone number and a Button for sending it as a D-Bus call.

import LaunchActions 1.0

Page {
   DBusMethodProxy {
       id: dBusMethodProxy
   }
   TextField {
      id: phoneNbrField
      width: parent.width
      inputMethodHints: Qt.ImhDialableCharactersOnly
      platformSipAttributes: SipAttributes {
          actionKeyEnabled: false
      }
   }
   Button {
      id: dbusButton
      text: "Call via D-Bus"
      onClicked: {
          dBusMethodProxy.call(phoneNbrField.text)
      }
   }

D-Bus methods can also be called from the command line, for example by using the qdbus command. The described example performs a similar operation as entering the following direct D-Bus command on the Harmattan device terminal:

qdbus com.nokia.telephony.callhistory /callhistory com.nokia.telephony.callhistory.dialer 123456

Further information

For more information on launching applications, see the following links:

• QDesktopServices Class Reference
• Platform API reference
• MIME types
• Desktop entry specification
• Desktop file utils (including update-desktop-database)
• XDG Base Directory specification
• URI scheme