Intro

Hello! I have something to show you. I’ve been working on a tool that teams up with Doxygen to produce .qch files (Qt Compressed Help) for use with Qt Assistant from your code documentation - a feature that has been asked for repeatedly since 2003 ([1][2][3]..). In this post I will introduce doxygen2qthelp, the answer to your request.

Download

You can grab the current code from our Subversion repository like this:

Building

I should mention doxygen2qthelp requires a Qt version later than 4.4.0, which at the moment means a snapshot of 2008-04-24 or later. If you start building now be sure to configure with -assistant-webkit. More about this later.

Background

Doxygen has been able to produce .chm files (Compressed HTML) from properly documented code. To be precise Doxygen does not create the .chm files itself: instead it produces a bunch of files that are used to instruct the Microsoft® HTML Help Compiler (hhc.exe). These three files contain the table of contens (file index.hhc), the list of keywords appearing in the index (file index.hhk), and a project description (file index.hhp). The former two of these are written in some form of "perverted HTML". What doxygen2qthelp does: take these files, parse through the soup, and create a ready-to-go .qch file for viewing in Qt Assistant. Alternatively, a fine-control .qhp file (Qt Help Project) can be produced.

Usage

Let’s say you were the author of the QWT library and you felt like shipping .qch files of your documentation. What would you do? Let’s first look at a manual approach, and see what we can automate after.

1. Enable Microsoft® HTML Help output
   First you need to tell Doxygen to generate HTML Help output. To do that you enable GENERATE_HTMLHELP
   GENERATE_HTMLHELP = YES

   in the Doxyfile. Without HHC_LOCATION being set Doxygen will just produced the index.hh* files and not try to call the Help Compiler from Microsoft®. That’s just how we like it, especially on our Linux Machine.

2. Run Doxygen
   If everything went smoothly we should have both HTML documentation and the index.hh* in doc/html/ .
3. Run doxygen2qthelp
   Now doxygen2qthelp comes into play. Invoke it from the QWT source folder like this:
   $ doxygen2qthelp --namespace=net.sourceforge.qwt --folder=qwt-5.0.2 doc/html/index.hhp qwt-5.0.2-doc.qch

   Alternatively you could also write this calls information into an .ini file and invoke it like this:

   $ doxygen2qthelp --config qwt.ini

   -- qwt.ini --
Namespace = net.sourceforge.qwt
VirtualFolder = qwt-5.0.2
InputFilename = doc/html/index.hhp
OutputFilename = qwt-5.0.2-doc.qch

4. Enjoy
   Open the documentation in Qt Assistant, preferrably a version from Qt 4.4.0 or later configured to use Webkit in Assistant (./configure -assistant-webkit). Without Webkit parts of the Doxygen HTML will look quite messy.

Automation

Wouldn’t it be cool if we could teach Doxygen to call doxygen2qthelp for us? Good news: I wrote a patch against Doxygen 1.5.6 for you (see doxygen_patch folder). Dimitri van Heesch and I planned to integrate that patch upstream for one of the next Doxygen releases.

1. Apply the patch and rebuild Doxygen
2. Add a few lines to the Doxyfile:
   ## Paths Relative to the 'html' folder!
GENERATE_HTMLHELP = YES
DOXYGEN2QTHELP_LOCATION = doxygen2qthelp
QTHELP_CONFIG = ../qwt.ini
QTHELP_FILE = ../qwt-5.0.2-doc.qch
3. Run Doxygen

That’s it - a single call to Doxygen can now produce .qch files.

Final words

Please report any bugs you might find through the Trolltech Bug tracker. Feedback is also welcome. Thank you!

So the time is finally here. Qt 4.4.0 was released a few weeks ago and as promised Qt Jambi is right behind. A lot of effort has gone into this one, in addition to supporting all the new Qt features, like Phonon, Webkit, Widgets in Graphics View, XQuery and Qt Concurrent, we also have a seriously improved deployment system, JDBC support and a compile-time checked signal-slot approach for the paranoid. Its a good time to be a Java developer I tell yah! We already mentioned all the featuers in the Qt Jambi 4.4.0 Preview Blog so we won’t repeat ourselves here… (There is a danger in linking to eskils blog, as it links to others again, which again links to others, which in the end proves to be a fairly complex graph, but then again… we are engineers and like that kind of stuff)

Under the cover we’ve also done quite some work. We also did an overhaul of the garbage collection and memory management subsystem and hopefully ironed out all the bumps and dents. We’ve also done some work on the build system, so that our users that build from source have a bit more substantial buildsystem to work with. Previously it was a complex install document, which has been replaced by a simple ant command which just does it all… I was very happy to see that the deployment system & ANT build scripts works well enough for the webstart to look like a plain, normal webstart app:

<resources>
<j2se version="1.5+"/>
<jar href="qtjambi-examples-4.4.0_01.jar"/>
<jar href="qtjambi-4.4.0_01.jar"/>
</resources>

<resources os="Windows" arch="x86">
<j2se version="1.5+"/>
<jar href="qtjambi-win32-msvc2005-4.4.0_01.jar"/>
</resources>

No magic nativejar or anything like that, just the qtjambi-win32-msvc2005-4.4.0_01.jar in the classpath and that is enough to load it, jpeg and svg plugins and all. The good thing is that the files included in the webstart are produced directly by the ant script with all dependencies etc set up properly… (well… almost properly, it took us an evening last week to get it really working, but now it works properly). Because of the fixes to memory management and deployment Eskil and I got these offical diplomas:

So, what more is there to say… Try the webstart with its new demos, download the packages and start hacking!

-
The Qt Jambi Team

Now that 4.4 is out, I finally found the time to kick off some new development and one of my pet projects these days is QGtkStyle. We already have QCleanlooks, icon themes, standard shortcuts and dialog buttons to integrate with GNOME, but to achieve true perfection we need to use the Gtk theme engine directly just like we do on Mac and Windows. QGtkStyle does exactly this, and in addition extends and surpasses QCleanlooks in a lot of other areas as well. All group boxes are now flat style to blend better with GNOME dialogs. Icon theme support has improved, scrollbar buttons are disabled at edges and item view branches now support hover.

The style is already available right now as a Qt 4.4 plugin on Labs and given that you can accept the normal disclaimers about using unreleased and experimental code, you can start playing with it immediately.

This is how the Arora browser looks:

All the above shots were taken using the “Clearlooks” engine. Here are a few alternatives:

Ubuntu Human:

Mythbuntu:

And of course the unforgettable Raleigh engine:

The cross-platform story for Qt becomes more and more true. Now we’re even going to be on Maemo it seems (kde people talk: here, osnews flamewar: here). However that was not really what I was going to talk about.

I have a little video for you here basically showing the Qt Everywhere demo running on both Windows Mobile and Embedded Linux side by side. We used the latest fancypants from HTC (Windows Mobile 6.0) and ran the Qt demos side by side to a Neo (Linux). Click the image below to check it out (opens new page, click play again):

The demo is basically just a small set of some of the Qt demos and examples that we launch and interact with in a more gesture inspired way. I love flicking those screengrabs around btw Skip ahead to 02:40 if you only want to see it running on the Neo…. Skip to 04:48 if you want to see the Neo die

One thing to notice here is that this demo-set was originally developed and compiled for Embedded Linux. All that was needed to have it running out of the box for Windows CE/Mobile was to add a few deployment rules to the .pro file for the demo. Now - it goes without saying that these demos run out of the box on our desktop platforms too.

Btw. stay tuned for the Open Source Development awards. We have a winner - and we’ve got prizes!

You might have wondered why there weren’t many blog entries about the acquisition - it was mostly due to legal reasons. Luckily, these have been resolved today, so I’m really happy that I can blog about the myriads of internal projects that we now have access to:

• Most kernels have neat schedulers, clever memory management and fancy device abstractions, but lack a good UI. The S40 phones are one step further - with Qt running in kernel space, they display a graphical kernel panic backtrace right on screen, together with fully functioning Restore/Restart/Quit buttons!
• That big companies often have communication problems can be seen in a fully functioning generator that creates C++ interfaces out of Qt Jambi APIs.
• There’s a lot of buzz about virtualization going on - and guess what we found! A phone hypervisor that paravirtualizes Linux. Similar to VMware’s “Unity Mode”, it is possible to run native and Qtopia applications side by side. Now, virtualization adds a certain overhead, so we were afraid that virtualized applications are too slow. To measure the performance, we ran the native and Qtopia’s Snake game side by side - and were astonished: Qtopia’s snake was running only about 6% slower than the native one!

  
  The virtualized snake (above) runs only about 6% slower than the native one (below)!

• There’s a hidden easter egg on most phones featuring T9 text completion (English locale only). Just create a new message and enter “27745027745″ into the text field for a funny effect.

On my way home from work today, I somehow found myself in an awkward situation, laughing as I saw an elder man that I don’t know hit the ground with a thump. Didn’t look too serious, but it most certainly hurt, and it really made my day. Hehe! A wonderful sense of euphoria went through my body as I wondered whether or not I should flip a coin into the air towards this unfortunate fellow, for reasons that probably wouldn’t strike your average observer as being glaringly obvious (in contrary, for also-oh-so-unobvious reasons this might have been perceived as a very rude thing to do, but I don’t quite know why).

So it all started when I was humming and strolling through the streets, past the shops near where I live. Sometimes I enjoy looking at all the funny people around me, at the silly signs people put up outside their stores. I decided to take a trip into the indoor mall. As the weather is pretty harsh sometimes in this country (rain/snow/wind) the mall has this double set of automatic glass doors, mounted like the sluice in a shape ship, to make sure cold air doesn’t get in, and warm air doesn’t get out. So anyway. As I close in on these doors from the outside, I suddenly stop up, and realize that the doors open very slowly today. They’re set up at about half speed. Probably because weather has been bad. I think, “That’s funny, hehe”, and then I continue walking in once the doors are completely open.

Now, as I’m on my way out again after buying a bag of raisin buns, I see two teenage girls approaching from the outside, all poshed up and chatting like teenage girls do, and suddenly I hear a loud “Bang!” as one of the girls has managed to bang her forehaid on the door as she walked in. “Hehe,” I found myself bursting out aloud. Her reaction was to give me, and then the half-open door the evil eye before shouting “Fy F#¤N i H#”#¤e, er det muuulig!?” [*] And so her friend naturally immediately concurred, “Ja fy f#¤n er det mulig.”

This is truly the age where on one side of the street, your average lady is facing a closed door, and blinking her eyes, hoping that that’ll remove this funny obstruction which she hasn’t encountered before. The door, on its side, is presenting its knob as best it can, wishing it could just say “Here!!! it’s right here!! it’s a KNOB!! you can use it to open me!!”. Your average guy walks straight into the shop window (i.e., that glass thing with no handles, next to the door) BANG, and curses the heavens above, rubbing his forehead and rushing away. These people are angry and upset with a wooden board, or a sheet of glass, failing to meet with their absolute requirements of not being in the way. Ah, astonishing.

And so it happens. Within two seconds after the last girl had just caught her breath, the guy, a man whom I do not know, walks BANG right into the same half-open door. The door did not open (with the speed that he was expecting). His predicted trajectory intersected that of the door-which-moveth-too-slow. This was an underperforming lame excuse for an automatic door. And so, he fell backwards, dropped his two bags, and whammed into the ground, and of course, he too, cursed out loud, and angry.

And I laughed. I’m evil. I’m sorry. I laughed out loud.

[*] The first girl’s outburst translates to “Oh, darn you bad devil from hell, is this not completely stupid, if at all possible?!?”. The other girl’s response would be something like “Yeah, I soo agree darn, you bad devil, it’s quite stupid, and not likely possible at all.” Norwegian teenage cursing is great fun :-D.

I am pleased to announce that Mark and I have now sent the final manuscript of C++ GUI Programming with Qt 4, Second Edition (ISBN 0132354160) to the publisher.

This extended and revised second edition has been thoroughly updated to take advantage of features introduced in Qt versions 4.2 and 4.3, including QGraphicsView and QDialogButtonBox, and features two new chapters and two new appendixes:

• Look and Feel Customization (covers style sheets and QStyle)
• Application Scripting (covers QtScript/ECMAScript)
• Building Qt Applications (covers qmake, cmake, bjam, and scons)
• Introduction to Qt Jambi

The original graphics chapter has been split into separate 2D and 3D chapters, which between them now cover the new graphics view classes and QPainter’s OpenGL back-end. In addition, much new material has been added to the Database, XML, and Embedded Programming (Qtopia) chapters.

This new edition is 180 pages longer that the previous one, and is available in hardcover. It is already possible to order it from Amazon.com.

From the preface:

This edition, like its predecessors, emphasizes explaining Qt programming and providing realistic examples, rather than simply rehashing or summarizing Qt’s extensive online documentation. Because the book teaches solid Qt 4 programming principles and practices, readers will easily be able to learn the new Qt modules that come out in Qt 4.4, Qt 4.5, and later Qt 4.x versions.

Since Qt 3.1, Assistant hasn’t been changed that much. In fact, I looks and works almost the same way as it did in Qt 3 times. We have received many suggestions for new features but were not able to implement them since most of them wouldn’t work well together with the Assistant structure, meaning they would have required fundamental changes to the code base. Now, for Qt 4.4. we are finally making a step forward by introducing a completely new help system.

The problem with the old Assistant as custom help viewer was that most people wanted to customize it more than it was possible. Some didn’t want the side bar at all, some others wanted it to be shown on the right instead of the left side and others wanted to have only the table of contents or indices shown. We also received suggestions to make only some of the menus or toolbars visible. Combining all those customizations would have added a lot of complexity which, in the end, may not even have satisfied all customers. That is why we went for the solution of providing a help library which offers the most important components for online help. The new Qt Assistant is basically just a reference application on top of the help library.

The new help library, called QtHelp, can be used for generating online help as well as retrieving its contents. The task of the retrieving part should be quite clear, but what about the generation part? Well, in contrast to the old Assistant, the new help system does not operate directly on html files any more. Instead, a new binary help file format was introduced which contains all the html files in compressed form along with the table of contents and indices. This should significantly ease up deployment since only one file has to be taken care of.

There are two ways of retrieving and displaying online help, either by using the help library or Assistant. Assistant, at first sight, looks pretty much like the old one, but having a closer look will show some differences. First of all, it is now possible to filter help contents according to their associated help attributes. This is especially helpful when having more than one (yes this is now possible as well!) Qt reference documentation installed. Secondly, navigating through the help contents can also be done by directly entering an url in the address bar. However, the most important fact is that Assistant does not contain any hard coded references to Qt documentation any more. So, every custom documentation integrated in Assistant has now the same possibilities, but also restrictions, as Qt documentation has.

The entire concept of having profiles has been given up in favor of using help collections. The main purpose of a help collection is to collect or reference one or more Qt binary help files. In addition, it can store nearly any data. In case of Assistant, the current help filter, the url of the currently displayed page or the location of its dock widgets - just to mention a few - will be saved. This removes the need of storing anything in the registry or .ini file which eliminates possible side effects seen with the old profiles approach. So, starting Assistant with a different help collection does not only change the set of help files but may also change its visual appearance.

The possibilities to change the visual appearance of Assistant are pretty much comparable to those existing in the old Assistant. However, some new ones like showing or hiding indices, bookmarks or table of contents were added.

Using Assistant as the help browser for an application saves a lot of time and effort. The downside is, that even though Assistant allows some customization it might still be too restrictive for some users. If this is the case, the help library should be deployed.

The help library provides models and views for indices and the table of contents, classes for full text search, functionality for accessing context sensitive help as well as functions for retrieving the actual help contents (usually html files). With the help of those components, it is easily possible to either implement a stand alone help viewer or, more conveniently, embed online help directly in an application.

Now, I guess it’s high time to let you know where you can find all this. Well, it has been integrated to our code base and you can get it by downloading a daily snapshot. Examples of how to use the QtHelp API (not 100% finished yet) can be found in the examples directory or in the Qt reference documentation.

The new Assistant is started by executing “assistant_new” (will be renamed). Since the new documentation format is not part of the daily snapshot yet, you have to either generate it yourself or download it from our help server. To generate it, simply call “make qch” in the root directory of Qt. Once the script is finished, restart Assistant and all Qt documentation will be shown.

Instead of generating the documentation yourself, it is much faster to download it from our help server. The help server can be accessed by opening the Edit|Preferences dialog in Assistant and activating the “Documentation” tab. Then select the “Download from Help Server” option from the “Install…” button. After a moment you’ll see a collection of currently available Qt documentation files. Select the ones you’re interested in and press “Install”. That’s it!

I love this application.

Ariya Hidayat has made a really neat Qt application/widget that does the “cover flow” thing we all know and love(?) from iTunes. Paul showed me the video of it running on the nice Chumby device (courtesy of Jesper) . And I thought: How would that run on my HTC Touch?, this nice little Windows Mobile phone I’ve got.

I just had to try.

And it’s freaking awesome. Have a look:

It’s really smooth and responsive. Specs for the phone:

• 200 MHz
• 240×320
• Windows Mobile 6.0

The video quality is not the best - but you get the idea.

If you want to check out the code go here.
If you want to check out the technology preview of Qt/WinCE then go here.