Enabling a splash screen

Applauncherd allows an application to show a splash screen if the mcompositor (the MeeGo 1.2 Harmattan window manager) is running.

The splash screen is not shown by default. If an application wants it to be shown, it must pass --splash, and optionally --splash-landscape arguments to the invoker. System default splash images can be obtained by giving default or default-landscape in place of image file names.

For instance, the following shows the splash screen with splash.jpg as its content when the device is in the portrait orientation:

/usr/bin/invoker --splash=/usr/share/application_name/splash.jpg --splash-landscape=/usr/share/application_name/splash-l.jpg --type=d /usr/bin/application_name

Otherwise splash-l.jpg is shown. If only --splash is given, that image is shown in both orientations.

The dimensions of both portrait and landscape images should be the same <screen width> X <screen height>; it means that mcompositor does not rotate the splash image, it should be drawn rotated.

Invoker passes the splash request to the booster. The booster sends the splash request to the window manager by setting a window property to window manager's window.

If the filenames do not include absolute paths, the window manager looks for the files from a default location.

The file should be in a format recognised by QPixmap, preferably JPEG as it is fast to load. Splash screen is always scaled to fit the full screen, hiding the status bar. Thus, the recommended size for the screen is 854 x 480 pixels. However, the figure is displayed even if the size is different.

Create a splash screen that resembles as much as possible the window that is shown when your application is launched. For instance, the splash screen can have the same background colour and toolbar as the application window. If the application window displays the status area, we recommend adding a black box with the same size to the splash screen of your application.

Splash and D-Bus interaction

If you want to invoke the application through D-Bus as well as from the application grid, follow the instructions in this section. This also applies to single instance behaviour provided by MApplication, so you may be using D-Bus even if there is no D-Bus related code in your application.

If splash is not used, the Exec line in the application's .desktop file may contain the invoker command line for starting the application. One of the first things that D-Bus enabled applications do is to register a service with the session D-Bus, which fails if another instance of the application is already running. In this case, an MApplication based application by default first calls the launch() D-Bus method of the existing application instance and then exits. The end result is that the existing instance is brought to the foreground and there is just one instance of the application running.

This changes when the --splash option is used in an invoker command in the Exec line of the .desktop file. When the application is started from the grid and there is already an instance of the application running, the following sequence of events takes place:

• The path to the splash image and the pid of the new application instance are passed to the compositor.
• The application's main() is called and the application starts to execute
• The compositor shows the splash image and starts to wait for the application with the specified pid to map a window.
• The freshly started application attempts to register the D-Bus service, fails, calls the launch() D-Bus method of the existing instance, and exits.
• The window of the already running application instance is mapped.
• The compositor ignores this window, because it has a different pid from the one specified in the splash request.
• The compositor finally gives up waiting for the specified pid to map a window, and fades out the splash screen, revealing the application window.

Deployment with splash and D-Bus on Harmattan

There are two ways to solve the D-Bus related problem described in the previous section. Firstly, you can use the single instance support of the invoker, and, secondly, you can use a D-Bus service in the .desktop file. The following examples demonstrate how to do this with the helloworld application.

In the first approach, there is an Exec line with invoker command in both the .desktop file and the .service file. Both lines use both the --single-instance flag and the --splash flag:

[Desktop Entry]
Type=Application
Name=Helloworld
Icon=icon-l-helloworld
Exec=/usr/bin/invoker --single-instance --splash /usr/share/helloworld/helloworld-splash.jpg --type=d /usr/bin/helloworld

[D-BUS Service]
Name=com.nokia.helloworld
Exec=/usr/bin/invoker --single-instance --splash /usr/share/helloworld/helloworld-splash.jpg --type=d /usr/bin/helloworld

In the second approach, the .desktop file specifies the D-Bus service, and the invoker command is in the Exec line of the .service file. In this case there is no need for the --single-instance flag. A minor problem is that the Exec line is required even if it is not used.

[Desktop Entry]
Type=Application
Name=Helloworld
Icon=icon-l-helloworld
Exec=/path/not/used
X-Maemo-Service=com.nokia.helloworld

[D-BUS Service]
Name=com.nokia.helloworld
Exec=/usr/bin/invoker --splash /usr/share/helloworld/helloworld-splash.jpg --type=d /usr/bin/helloworld