API

assistant update

Posted Sat, 02/09/2008 - 18:18 by matt

After my post a few days ago I recieved an email from Thomas Strehl at Trolltech who kindly explained a few points about the new assistant to me. It seems it's already more powerful than I thought. Instead of having to manually load the 'help collection' into assistant, one can pass a command line argument and load a specific help collection, you can then specify in that help collection the window icon, window title etc. and this way it would be very easy to create a "KDE API browser". It's as simple as doing

assistant -collectionfile kdelibs.qhc

from the directory where kdelibs.qhc is located. Given the currently lacking documentation, I'm not sure how to set the icon etc. but it WILL be possible.

Thomas also hinted that Trolltech are working on a generator to create QHelp binaries directly from Doxygen output, making pretty much everyone's life easier. I guess the next step is to try to get docbook files loading :)

If we can get all that working nicely, it might be worthwhile looking into porting/rewriting KHelpCenter to use the QHelp library. Does anyone know the current status of KHelpCenter? The last I remember, after my post a while back PhilRod and co. were working on it. Does it need a breath of fresh air?

The other benefit of using QHelp would be that once docbook files are loaded in, it would be possible to query the database from within applications and display help in 'WhatsThis' hints, which, as I remember was one of the big points that we mentioned at the doc meeting a few months back. Another use-case would be KDevelop displaying apidocs for functions more easily.

I think that QHelp will provide us with an excellent opportunity to revamp our documentation system thanks to Trolltech once again thinking about what their users want and doing the dirty work in writing the library.

kdelibs in assistant

Posted Wed, 02/06/2008 - 23:32 by matt

Finally, Qt (in 4.4) has got a new documentation viewer and library. While playing around with it and reading the documentation to try to get the Qt apidocs working, I realised that it wouldn't be too hard to get the kdelibs (and other modules') documentation loading in it. After a bit of playing around with KDE's doxygen scripts, I got something looking a bit like this:

Now, I know it's not the prettiest layout but it's early days yet. To try it out yourself, download the patch from http://milliams.com/uploads/qhelpkdelibs.diff.tar.bz2 and apply it to your base kdelibs directory. Then execute the following commands (of course, you need a Qt 4.4 snapshot):

cd doc/api
./doxygen-qhelp.sh ../../
cd kdelibs-apidocs
qcollectiongenerator kdelibs.qhcp -o kdelibs.qhc

Both the doxygen-qhelp.sh and qcollectiongenerator commands will take quite a while to do their stuff, so be patient. You'll probably also get a load of warnings from qcollectiongenerator since the file list was generated from an oldish checkout. Once the kdelibs.qch file has been created (it will be about 90 MB), open the assistant from Qt 4.4, go to "Edit → Preferences... → Documentation" then "Add → From local file system..." and select the kdelibs.qch file from the doc/api/kdelibs-apidocs directory. You may have to close and open assistant to get the collection to show up in the left-hand menu. But once it is, searching and the rest should mostly work.

Now, the file list was generated by a script but all the rest was hand-written. Ideally, all these files should be fully automated, perhaps by extracting some of the information from the .tag files. Once the system is made better and more automated, perhaps this sort of thing should be available for download from api.kde.org to replace (or augument) the current, static HTML download. I'll look to getting the rest of the modules working (should be quite easy now) and then I'll try to get some application handbook docbook files loading in.

Writing APIs the Ruby way

Posted Tue, 05/22/2007 - 23:46 by matt

Recently I've been working on some library classes for the KDE4 Games module. Firstly a high score table system and more recently extending Mauricio Piacentini's KThemeSelector to use KNewStuff2 and make it usable by any game in the module.

This is the first time I've worked on any sort public API so it was interesting to see the way I do it compared to the rest of KDE/Qt.

Now I've never actually used Ruby. All I've done is read a few articles on it and look at a tutorial or two. I can't remember anything substantial about the language but the one thing that has stuck in my mind about it is it's design philosophy that is most often talked about. That is the way that it caters for the majority of uses by default. By that I mean most classes that are ever written will, for 90% of the time, only be used in one specific way. With maybe a few lines of code that are the same every time the class is used. It is only 10% of the time that the class is used in a way that is out of the ordinary. Because of this rule, API should be tailored towards making it really easy for the 90% of people who only want to do basic things.

Now this sounds like very good philosophy to have when writing an API which is providing an easy way to implement a highscore table or a theme loader. Most tasks should be possible in three lines of code and only the unusual tasks (like custom score fields or loading themes from a different directory) should require more. I think I achieved that with KScoreDialog.

Incidentally, hello PlanetKDE.org! I'm Matt Williams (milliams on IRC/SVN). I've been actively hacking KDE for about 6 months (though I've been helping out with various other bits for a while before that) now and I'm currently working on kdegames and doing a little bit of work on Plasma.

Refactoring all round

Posted Tue, 01/09/2007 - 23:29 by matt

Yesterday, I massively refactored KSquares. Basically, there was too much code in the QGraphicsScene class which was handling game data. For example, it was responsible for checking for any completed squares every time a new line was drawn. As a result of this there were signals flying everywhere - mostly to KSquaresGame, the class that's supposed to be the game controller - which was nastily messy. I moved all game specific code into the KSquaresGame class and so could vastly simplify the API of both classes. A side effect of this refactoring is that it makes it easier when I come to add network support.

All this refactoring got me in the mood to do a bit more work on Sparkle. The code that's currently in the repository was always intended to be rewritten (maybe several times) and I figured today would be a good chance. I feel at the moment, the code structure is too complex. I need to plan better how everything is going to fit together and how to most efficiently describe the relationships between different objects.

P.S. If anyone's tried KSquares, I'd love to hear what you think of it as I've had no feedback yet :D

Sparkle, KSquares et cetera

Posted Tue, 09/26/2006 - 22:49 by matt

Okay, loads has happened since my last post.

I started work on a 2D physics engine. You can see what I've managed so far at its Sourceforge page. The code is all in subversion atm. It's certainly a WIP and won't really blow anyone's socks off since all it really does at the moment is crash :D

Also, in preparation for doing some proper KDE work I decided to learn my way around the API a little. With the help of annma's KAppTemplate/kapp4 I managed, in only a day or two to write a little game that uses KDE4. It's based on that game 'squares' that is another great timewaster in the same category as Noughts and Crosses. Version 0.1 can be downloaded from this site but be aware that it will require KDE4 and CMake etc.

Syndicate content