Libsailfishapp Docs

API Documentation

SailfishApp Namespace

The SailfishApp namespace allows the easy creation of Sailfish applications. More...

Header: #include <sailfishapp.h>

Functions

QGuiApplication *	application(int &argc, char **argv)
QQuickView *	createView()
int	main(int &argc, char **argv)
QUrl	pathTo(const QString &filename)
QUrl	pathToMainQml()

Detailed Description

The SailfishApp namespace allows the easy creation of Sailfish applications.

When creating a QT application for use on Sailfish OS, the functions in the SailfishApp namespace provide a simple and minimal way to manage your application lifecycle, provide a QML interface, a QT event loop, and manage resources.

To use libsailfishapp in your project:

Add BuildRequires: pkgconfig(sailfishapp) to your .spec file
Set TARGET = harbour-yourappname in your .pro file
Add CONFIG += sailfishapp to your .pro file
Include sailfishapp.h in your .cpp file
Use the SailfishApp:: methods in your main()

Example of usage:

 #include <QtQuick>
 #include <QDebug>
 #include <sailfishapp.h>

 int main(int argc, char *argv[])
 {
     QScopedPointer<QGuiApplication> app(SailfishApp::application(argc, argv));
     QScopedPointer<QQuickView> view(SailfishApp::createView());

     view->setSource(SailfishApp::pathTo(QString("qml/main.qml")));
     view->show();

     return app->exec();
 }

Function Documentation

QGuiApplication SailfishApp::application(int &argc*, char ***argv*)

Create a new QGuiApplication instance configured for use on Sailfish OS

Creates and configures a QGuiApplication ready to be used as part of a Sailfish application.

After having removed any arguments passed to main that your application is specifically interested in, the remaining arguments should be passed on to this call.

The QGuiApplication instance returned is owned by your application, so should be deleted when no longer needed.

The argc and argv parameters are the command-line parameters to pass in for interpretation. The argv parameter is an array of pointers to zero-terminated strings to be interpreted, while argc is the length of this arrary (the number of parameters to interpret).

Returns a new QGuiApplication instance to use for your application.

QQuickView *SailfishApp::createView()

Create a QQuickView instance for use by your application.

Creates a new QQuickView instance that your application can use to display its user interface. The QQuickView can be used, for example, to set up the root QML page to be displayed by your application.

The QQuickView instance returned is owned by your application, so should be deleted when no longer needed.

Returns a new QQuickView instance to use for your user interface.

int SailfishApp::main(int &argc, char ***argv*)

A convenience function for getting a Sailfish app up-and-running with minimal fuss

If your application is primarily QML-based, with limited need for interactions with C++, then you can use this call to get your application up-and-running as swiftly and painlessly as possible. Ensure you have a QML file called qml/$$TARGET.qml inside your application's data install directory (so usually this would be a file /usr/share/$$TARGET/qml/$$TARGET.qml ) and then simply call main to start your application's Qt event loop.

Using this approach you can get a minimal application running using the following code.

 #include <sailfishapp.h>

 int main(int argc, char *argv[])
 {
     return SailfishApp::main(argc, argv);
 }

After having removed any arguments passed to main that your application is specifically interested in, the remaining arguments should be passed on to this call.

The return value of the call can be used as the return value for the application. On normal exit a zero value will be returned, any other value represents an abnormal exit.

The argc and argv parameters are the command-line parameters to pass in for interpretation. The argv parameter is an array of pointers to zero-terminated strings to be interpreted, while argc is the length of this arrary (the number of parameters to interpret).

Returns the result of the application execution. Zero for normal exit, non-zero for anything else.

QUrl SailfishApp::pathTo(const QString &filename)

Convert a relative resource path into a fully qualified path specific to the application

Used to find the fully qualified path of a file contained within the application's data directory. The filename parameter should specificify the file relative to the base of the data directory. The returned URL will be a fully qualified path pointing to the file.

The data directory is usually found at /usr/share/$$TARGET (where $$TARGET is the application name), so for an app called harbour-myapp and an input filename of "qml\myApp.qml" the resulting file would be found at /usr/share/harbour-myapp/qml/myApp.qml

The filename parameter represents the path relative to the application's data directory.

Returns A fully qualified path pointing to the file.

QUrl SailfishApp::pathToMainQml()

Returns the path to the QML file used as the root of the application UI

This function is used to get a path on the local filesystem of the qml file that is opened when your application starts, and that will form the root of all other QML files displayed by your application. The file should contain an ApplicationWindow that links to the initial page used for the application, and the cover page to be used on the app screen, similar to the following.

 import QtQuick 2.0
 import Sailfish.Silica 1.0

 ApplicationWindow
 {
     initialPage: Component { MainPage { } }
         // ... Points to the first page to be displayed
     cover: Qt.resolvedUrl("cover/CoverPage.qml")
         // ... Points to the file to be used for the app screen cover
     allowedOrientations: defaultAllowedOrientations
 }

The path returned will usually be of the form /usr/share/$$TARGET/qml/$$TARGET.qml (where $$TARGET is the application name), so for an app called harbour-myapp the path returned would be /usr/share/harbour-myapp/qml/harbour-myapp.qml