We write a desktop widget under Maemo5 on Qt. Part Two and Final

Good day, Habrauser. Continuing the series of articles about the Nokia N900. And I continue the article started last time about writing a widget for the N900 on Qt . And so, last time we made a simple application that receives a list from a file in a special format (xml). This time we will complete this application and turn it into such a desktop widget:

Since I am writing more about Maemo5 (MeeGo in the future), I will try to pay less attention to Qt and more integration with Maemo5 / Hildon. And I’m really trying to show that developing applications on Qt does not require knowledge of the specifics of the platform and the “native environment” (in our case, it’s GTK).
In this article I will write about how:

1. Write a delegate for a "beautiful" display of information.
2. Implement your own model to ensure the functionality of the application.
3. Make a composite widget from several other widgets and a set of functionality.
4. Make it like a desktop widget and make a .deb package.
5. Add a settings page to this widget.

Most importantly, all of the above does not require special in-depth knowledge and adaptation of the application for Maemo5, the resulting widget can work perfectly on the desktop system (Mac / Win / Lin), but not as a desktop widget, but as a simple application.

Delegate to display the list

First of all, you need to decide what and how to display. Adequate minimum of information:

1. Departure time.
2. How much time is left before departure.
3. Notes (on what dates, on which days).

Having decided a little, I decided to do this: display the time before departure in large numbers and the time of departure after a space. I decided to make the color of the time before departure dynamically. For example, if less than 5 minutes are left before departure, it will be drawn in red; if less than 15 minutes, it will be dark yellow. If before departure more than 15 minutes - then it is dark blue. It turns out two thresholds. In my example, these are 5 and 15 minutes. It was decided to make these thresholds customizable and put them into settings (platform-specific storage, QSettings) It would be nice to make the colors themselves customizable, but let it be in the Roadmap. Immediately after the previous two fields, you need to place a note on the entire remaining space. Moreover, the height should fit two lines of text from the note, since the note can contain a lot of information.
In the end, it should look something like this:

Due to the fact that no one responded to my request for help in the design of the application interface, I decided to do everything on my own. Since I am not particularly strong in this design, I decided to entrust the rendering of list items to the maximum on the system. Because of this, the code of the delegate who is responsible for rendering this list item has become a bit complicated and needs additional description (but managed to demonstrate a style-independent rendering of the widget).

To implement the delegate, you need to overlap only two methods (since our delegate does not modify the data):

void paint(QPainter * painter,const QStyleOptionViewItem & option, const QModelIndex & index) const;
QSize sizeHint (const QStyleOptionViewItem & option, const QModelIndex& index) const;

* This source code was highlighted with Source Code Highlighter.

The first method draws an element, and the second returns the necessary dimensions to draw one element. Well, actually the delegate itself is the heir to QStyledItemDelegate. You can read more about deregs in the official documentation. Due to the fact that we inherited from the stylized delegate, in both of the above methods in the form of parameters we get the QStyleOptionViewItem variable. Thanks to this variable, you can "reach out" to the parameters of the current style. Here are some examples:

• option.rect - dimensions of the rectangle to draw
• option.palette - QPallete for drawing
• option.palette.text (). color () - the text color of the current palette for drawing
• option.state - state of the current element (an element can be selected, for example)
• option.font.pointSize () - font size
• option.palette.base () - base palette
• option.palette.alternateBase () - alternative base palette

A lot of different information is available in Qt and I would recommend that you familiarize yourself with the widget rendering system using styles to understand how and what is used.
As you can see from my code, I used the fontDelta static constant to determine the font size for drawing time and notes. It is 3 on the desktop system and 6 on the Mayo5 device (N900). This is a very "dirty" workaround or in common people - a nail. It is connected with the fact that on N900 with delta 6 two lines of notes are placed on one time line, and on the desktop system with delta equal to 3. Here is an example of incorrect rendering:

But if a system appears for which the delta will already be different, then you will need to add another value with the delta, which is very not good. Therefore, this delta must be calculated programmatically (using QFonrMetrics for example). So this implementation is draft and temporary. Nevertheless, as a result, we got a delegate who drew the following on the screen:

I believe that the result was readable and beautiful. The lines are highlighted by shading (even ones have one color, and odd ones have another). And the colors for the substrate of even and odd lines correspond to system ones (system colors can be entered in the background in the debugger window).

Controls

Since we can have several schedules (at least you need to have two schedules: “there” and “back”), you need to be able to switch between them. To do this, I thought of two arrows: "forward" and "back" on the list of schedules. To know which schedule is currently displayed, you need to place text with the name of the direction on the widget. In the process of 4-minute design, I got the following widget:

When I click on the left and right arrows, I switch to the previous and next schedule in the schedule list.
By clicking on the inscriptions with the direction - the list is positioned on the nearest poisonous train.
Looking ahead, I’ll tell you that the widget on the desktop “not correctly” intercepts the event of scrolling and dragging the mouse. Therefore, it was not possible to scroll through the list either with the help of the scroll bar or with the usual scrolling with a finger (touched and held up or down). The problem was solved in this way: if you click on an element in the list located above the middle of the displayed list, the list will “scroll” in such a way that this element will be the last in the visible section of the list (Scroll Up):

And if you click on the element located below the middle visible list, it will become the first in the visible list, respectively (Scroll Down):

Well, the update of the time remaining before departure is updated by timer every minute. And the list itself updates data from the network when loading or when closing the settings window.

Model

The model has been modified slightly from the previous state. A list of schedules was added, as it became possible to manipulate multiple schedules. It would be more correct for each individual schedule to instantiate its model, and in the widget switch between them. But since I initially “hid the loading mechanism in the model” and everything connected with it there, it was more logical and easier to transfer the list of schedules to the model. Therefore, I ask you not to criticize strongly for such a deviation from the template (all the more so since in this particular example there are practically no “losses” from this “deviation”).

Launch as a regular application

If you run the resulting code at this stage, then we get the application. Not having any mention of widgets and Maemo5. The result of execution on the N900 you see above.
This is how the application looks on Mac OS:

In the simulator for button symbian phones on the example of N95, the result looks like this:

well, for the touch simbians on the example of N97 like this:

The result was good. Under each system, the list is displayed in “native” colors, although it is completely drawn by our code. Moreover, if you change the style on the device, the list will also change accordingly. Which is very cool, as it will make the widget "native" for any installed style.

Start

It is from here that you can start writing an article. Everything that was before this has nothing to do with mobile development. This is an introduction. But I wanted to show the whole cycle of writing an application for the N900, to show that the development for the N900 (or another Qt platform, Symbian for example) is no different from the development of a desktop application on Qt. Moreover, developing Qt applications for mobile platforms is for the most part a regular Qt development.
The application that we have now is not tied to any platform. It can be built and run on any supported platform without changing the code at all.

Identification

In some cases, it is necessary to “understand” in the code what platform and with what parameters the application is going. And in Qt code, you can apply the following preprocessor definitions: Q_WS_XXXXXX. It stands for “Qt Window System”. For Maemo, it will sound like this: Q_WS_MAEMO_5. In the .pro file, there are branching commands for each platform: win, mac, maemo5 ... This also needs to be used to identify the platform if you need to use code specific to that platform. In order to understand that we are collecting code for Maemo5 and the application is being assembled as a desktop widget, the code uses the standard Q_WS_MAEMO5 directive and the introduced RASP_WIDGET directive. If there is no last directive, then the project is assembled as a simple application for the Maemo5 platform.

Widget creation

There is a special project, which is an adapter, implemented on the basis of the "bridge" template. On the one hand, this is the Hildon interface of the desktop widget, and on the second, it is a QObject for interacting with Qt code. It is called QMaemo5HomescreenAdaptor and a package with source code and an example can be downloaded here. All you need to do is add a section to the .pro file with approximately the following contents:

maemo5: contains (DEFINES, RASP_WIDGET): include (./ qmaemo5homescreenadaptor / qmaemo5homescreenadaptor.pri)

That is, if the project is being assembled for maemo5 and the RASP_WIDGET preprocessor directive is specified, then we add the embedded project of the desktop adapter to the project.
And in the main.cpp file we add the following code:

#elif defined(Q_WS_MAEMO_5) && defined(RASP_WIDGET)
  QMaemo5HomescreenAdaptor *adaptor = new QMaemo5HomescreenAdaptor(&w);
  adaptor->setSettingsAvailable(true);
  QObject::connect(adaptor, SIGNAL(settingsRequested()), &w, SLOT(showSettingsDialog()));
  w.show();
#elif defined(Q_WS_MAEMO_5)
  w.showMaximized();
#else
  w.show();
#endif

* This source code was highlighted with Source Code Highlighter.

Everything is simple here: if we assemble the widget, we create an adapter and connect the signal about the call of the settings window to the corresponding slot of the widget. If you build the project as an application for Maemo5 (not a widget), the adapter is not created, and the widget is displayed in full screen.

And you also need to remember to add the adapter header file in the header of the main.cpp file:

#if defined(Q_WS_MAEMO_5) && defined(RASP_WIDGET)
#include "qmaemo5homescreenadaptor.h"
#endif

* This source code was highlighted with Source Code Highlighter.

That's all. All code for implementing the widget is written. But you can’t just launch it as a widget, you need to install it in the system as a desktop widget. And for this you need to collect the .deb package.

Widget assembly in .deb package

This part is the most terrible and complicated. Since I did not succeed in debugging the application on the device as a widget, you can check the final result only by collecting the package and installing it on the device.
I took this very useful article as a basis .
Now step by step. To execute all the commands you need to register the path to the binaries from MADDE. Under Windows, it is enough to run a special terminal, available in the Nokia Qt SDK item after installation. Under * nix systems, you just need to add the path to the PATH variable:

export PATH = ~ / NokiaQtSDK / Maemo / 4.6.2 / bin /: $ PATH

The environment can be considered customized.

1. Create a directory

Next, create a separate directory with the name <application name> - <version number>. And strictly in this form. In my case, it turns out: "rule-raspisanie-widget-0.1." This is what the resulting application will be called in the package manager. After that we drag everything we need there to build the application: .pro, .cpp, .h, .qrc ,.

2. Create a .desktop file

In my case, this is the content of this file:

[Desktop Entry]
Name = Qt desktop timetable
Comment = Qt based widget example for habrahabr
Type = qt
X-Path = / opt / rule-raspisanie-widget / raspisanie
X-Multiple-Instances = false
X-home-applet-minwidth = 200
X-home-applet-minheight = 200

There are no special comments needed. The main thing here is to specify the path to the executable file - "X-Path" and disable the ability to run multiple instances of the application - "X-Multiple-Instances". You can read more about the file format here and here .

3. Change the .pro file

This .desktop file must be copied to a specific folder on the system during installation, so you need to add this rule to the .pro file so that the corresponding rule is generated in the Makefile.
Add the following lines to the .pro file in the section with maemo5:

PREFIX = debian / rule-raspisanie-widget
desktop.path = $$ PREFIX / usr / share / applications / hildon-home
desktop.files = * .desktop

target.path = $$ PREFIX / opt / rule-raspisanie-widget /
INSTALLS + = target desktop

Here the prefix is ​​the root of the system in the .deb package. The above code takes two steps:

• Creates a new "desktop" rule with the path "/ usr / share / applications / hildon-home" installed on the target system. The objects of this purpose are all .desktop files.
• Assigns the path “/ opt / rule-raspisanie-widget /” for installation purpose of the project (in our case, this is an executable file) at the installation stage, thanks to this the assembly target (the resulting application) will be copied to “/ opt / rule-raspisanie-widget / "during installation.

Adding new build steps to a .pro file is a fairly powerful tool, and I recommend getting to know it better .

4. Generate a skeleton for the .deb package

In this step, MADDE will do everything for us, all that needs to be done is to execute the following command in the created directory:

mad dh_make -createorig -single -ea@example.com -c gpl

You can read more about packaging using MADDE in the official documentation .
After that, the “debian” directory will appear with a bunch of files inside. We will need to adjust some of them.

control file

This file contains all the information needed to build and install the application.
This is how this file looks like:

Source: rule-raspisanie-widget
Section: user / desktop
Priority: extra
Maintainer: Ievgen Rudenko
Build-Depends: debhelper (> = 5), libqt4-dev (> = 4.6.1), libhildon1-dev, libhildondesktop1-dev
Standards-Version: 3.7.3
Homepage: < erudenko.com , rule.habrahabr.ru >

Package : rule-raspisanie-widget
Architecture: any
Depends: $ {shlibs: Depends}, $ {misc: Depends}, qt4-homescreen-loader
Description: The test widget for desktop, shoew timetable
It's Qt example of making Desktop Widget for Maemo.
It's Timetable that use simple XML format to retrieve via web.

Important parameters are:

• Build-Depends - here you need to register what packages the application build depends on, in our case it is Qt - libqt4-dev (> = 4.6.1) and two more packages for the adapter (libhildon1-dev, libhildondesktop1-dev);
• Depends - indicate which packages must be in the system to run the application. Our application requires the qt4-homescreen-loader adapter;
• Section - which category the application belongs to (information for the package manager).

Well, of course, do not forget to fill in the fields with the name, maintainer and description.

rules file

This file describes the steps for building a project. You need to write in it that you first need to run qmake before doing make (to generate a Makefile) at the build stage and the same for the cleanup phase.
We are looking for the rule build-stamp: configure-stamp and edit it (bold is what needs to be inserted):

build-stamp: configure-stamp
dh_testdir

# Add here commands to compile the package.
qmake "DEFINES + = RASP_WIDGET" && $ (MAKE)

Do not forget about the Makefile format: before each step, to assemble the target, you must put a tab character .
Now we change the cleaning step, look for the goal of the same name - clean in the rules file and change it accordingly. After the change, this step will look like this:

clean:
dh_testdir
dh_testroot
rm -f build-stamp configure-stamp

# Add here commands to clean up after the build process.
qmake "DEFINES + = RASP_WIDGET" && $ (MAKE) clean

dh_clean

postinst file

This file is executed after installing the package on the system and here you can write additional commands, if necessary. In our case, we need to bypass one small bug in MADDE, which consists in the fact that the application "reset" the "x" flag of the application, informing that the file is executive. All you need to do is write a command in the file to set this flag:

#! / bin / sh
chmod + x / opt / rule-raspisanie-widget / raspisanie

Thus, after installation, this script will be launched, which will set the “x” flag to our application.

file "compat"

According to the documentation , this is the version file for checking compatibility with Debhelper: “Debian helper compatibily version.” Just make sure there is a "5", not a "7".

5. We collect .deb package

Everything is ready, all you need to do is execute the command:

mad dpkg-buildpackage -us -uc

And in the directory up to "../" you will find three files with the package name and extensions: dsc, tar.gz, changes, deb. This is the last one we need.
PS: You can read more about the above "shamanism" in the documentation for creating .deb packages .

Install the resulting package

I did it simply - I copied it using scp to the device and ran it from the standard file manager directly on the device. After that, the package was installed and you just need to add the widget to the desktop in the usual way and everything will work. You can also send yourself by mail in the attachments and if you double-click on the attached .deb package on the device, the package manager will automatically open and install the package from the message attachment.
You can also do this using the “dpkg -i” commands on the device via ssh or the MADDE Device Runtime .

Rebuild the .deb package

Here, too, everything is simple: we delete the generated dsc, tar.gz, changes, deb files. Copy the new sources over the old ones in the package build folder and run the command again:

mad dpkg-buildpackage -us -uc

We remove our application using the package manager and install the new package using one of the above methods.

conclusions

You can watch the resulting result at the very top, this is a screenshot from my N900. The application is not perfect, and clearly needs further development, but it is quite functional and performs basic functions. I consider the main task (writing an application without platform knowledge) to be completed. The only thing I had to tinker with was packing into a .deb file. But first, this package format is not specific to Maemo. And secondly, in the next releases of MADDE, all these steps will be “hidden” in Qt-Creator (most of them are already hidden).

Total time spent in the second step:

• refinement of existing code and debugging: 3 hours
• Examination of documentation and packaging information in .deb: 30 minutes
• debugging the application as a “desktop widget": 1 hour

Total time 4 and a half hours. If we take into account the "first stage" , then the total time for creating the application is almost 7 hours. One business day.
It took me about 16 hours of pure time to write this article (almost a week of "dirty"). So it’s more profitable to write code than articles :-)

The code can be downloaded from here .
A directory with a blank for creating a .deb package can be downloaded from here .