KDE Development - Part 11

From LXF Wiki

Table of contents

USING KDEVELOP

KDE Development PART 11

Jono Bacon clears his desk as he wraps up this long-running and popular series ­ but not before showing you how to take your project public.

Welcome to the final part of our KDE development series. From small seeds we have coaxed our LXFGallery program into the confident specimen it is now. Throughout this 1 1-part series we have continued to massage and grow our creation by adding features such as as user interface elements, interaction, thumbnails, an HTML web gallery and other nuts and bolts. As a newcomer to the world of KDE development, you have seen a glimpse of what the extensive KDE development system offers.

With the final part of the series upon us, we will pull together the threads and bring our coverage to a close. The first task to cover this month is finishing off our implementation of the web photo gallery by providing the means to upload some photos to a web resource using the KDE framework.

We will then discuss some of the other possibilities and technologies involved in writing desktop software for Linux. This should provide some inspiration for you to continue your learning and push your KDE programming further.

Transferring images


In the last issue (LXF63) we started to build a facility to generate a web photo gallery. The process involved creating some code in which you can generate a HTML page called index.html that displays a list of thumbnail images that can be clicked to view to full-size images. This thumbnail preview is a common feature within many photo gallery applications, and this month we will discuss how to get the photos from your hard disk on to a machine somewhere out there in the ether of the internet.


Networking with KDE


Ever since KDE's inception, the KDE project team have been building a reputation for turning framework construction into an art form. In the early days of KDE development, the KDE hackers created some essential frameworks for key development requirements, and since then the KDE project has presented eager developers with a framework for just about anything you can imagine.

With the impending 4.x series of KDE releases, the framework count continues to grow. Although some feel that throwing more tools at a problem instead of writing software to solve it is a bad method of programming, we will sidestep some of the political views and instead concentrate on one specific core framework: KDE IO Slaves.

KDE IO Slaves blurs the concept of what is a local resource and what is a remote resource. In any kind of network programming, there has traditionally been a certain amount of cramming involved in learning how to make use of a particular type of network resource. This involves learning how data is streamed back and forth, how the the protocol works, the limitations of the resource, permissions and other issues. Although this is perfectly understandable for learning a new technology, many of the underlying concepts are mere details in very similar behaviour - sending data back and forth between one computer and another.

The KDE team have worked to create a framework in which, at the API level at least, remote data transfer can be standardised. This means that if you want to include some code in your program to connect to an FTP server and transfer files, you should be able to use the same or very similar code to change from one protocol to another. This feature was originally developed with the Konqueror web browser in mind, but the technology was considered compelling enough to be made part of the general KDE platform.

This networking system is modular, and there are a number of `slaves' for different networking needs. Although you would expect KDE IO Slaves to be only used for networking, other slaves exist for compression formats such as gzip and for extracting audio tracks from a CD. With such a modular system, the KDE team are able to constantly write and improve the KDE IO Slave system and augment current slaves with new ones as new technologies muscle their way into the world.

Using a KDE IO Slave is straightforward. The system requires a URL to indicate where a resource is located, and this URL includes some information prepended to indicate the type of resource and which slave should be used to deal with it. As an example, if you were to indicate your URL as ftp://foo.com, it's clear from the URL that this resource is an FTP site. From this information, the resource can be contacted and dealt with accordingly.

Another interesting point to make about these KDE IO Slaves is that they are asynchronous. This means that more than one connection can occur at any one time, which is particularly important when you need to deal with more than one protocol or resource at any one time in your program. Slave to the grind Implementing a KDE IO Slave for our photo gallery's FTP needs is fairly simple. Instead of running through the process of adding the user interface frosting to access this functionality, I will leave that for you to do. If you are unsure of where to start, revisit the last issue when we added a menu item for the web gallery option in the File menu. In this issue, we will concentrate on writing the slot, and you can then merge the functionality into your interface where you want to.

The first step is to create a list of pictures in memory, complete with the path to where they are stored on your hard disk. To do this, we will use the familiar QStringList class that we have used in previous parts of the series. Add this code below `QStringList pathList;' in selectionbarcode.h:

 QStringList imageList;

You now need to populate the QStringList with this information. The best place to do this is in the loadThumbs() slot where you created the thumbnail view. Add the following line of code under the line where you created the `pix' QPixmap:

 imageList.append(fileinc->absFilePath().latin1());

In this line of code you add the absolute path of the file to the QStringList when each thumbnail is added to the view. When this slot has finished, the imageList QStringList will contain a complete list of the images in the album.

The next step is to create a new slot in selectionbarcode.h where the code for the KDE IO Slave action will happen. Add this to the `public slots:' part of the class:

 void uploadFiles();

Now create the slot implementation in selectionbarcode.cpp:

void SelectionBarCode::uploadFiles()
{

Here we create a new slot called uploadFiles(). The first lines of code in this slot should check if the imageList QStringList has anything in it; and if not, to exit the slot:

if(imageList.isEmpty())
             return;

If there is data in imageList, we can write the code to perform the upload:

else {

The first line in this block should specify the URL of where the networked resource is located. To do this we will create a string using QString and call it `ftp'. This string has a very distinctive format:

QString ftp("ftp://anonymous:anonymous@foo.com");

In this example we are using an online FTP site, and we prepend the URL with ftp:// to indicate that it is an FTP resource. This part at the beginning of the URL is required so that the KDE IO Slave system knows which IO Slave to use for the request. Another key part of this URL is the `anonymous: anonymous' part. This is the username (left `anonymous') and password (right `anonymous') for the site, and you should include these where possible.

The next step is to create a loop in which we can upload each image in the imageList string list, overleaf:

for(QStringList::Iterator it=imageList.begin(); it !=imageList.
 end(); ++it)
 {

In the above line, we are using QStringList::Iterator to create an iterator called `it' that uses begin() to mark the beginning point of the QStringList. We then loop while each iteration is not equal to imageList.end() (the end of the string list) and we loop one iteration at a time (++it). This code will basically loop through each item in the QStringList one by one.

Next, you need to create a KURL (KDE URL handler) that refers to a pointer to the iterator we have just created:

KURL currentUrl(*it);

We can use this iterator in the next line to actually copy the file. We will use the file_copy() function within KIO::NetAccess KDE IO Slave to copy the file. The following line encases the file_copy function inside an `if' conditional statement to see if the function runs successfully. If it doesn't, an error notification is sent to the KDE debugging subsystem:

 if(!KIO::NetAccess::file_copy(currentUrl,KURL(ftp+(*it).
 section(`/',-1))))
              kdDebug() << "Error :" << KIO::NetAccess::
 lastErrorString() << endl;
 }

The file_copy() function takes the URL and the iteration pointer, and uses the section() method to cut out the absolute path and simply upload the filename. This section() method uses `/' as the symbol that separates the different parts of the string. Specifying -1 will use the last part of the string (the filename).

Finally, close off the remaining blocks with curly brackets:

              }
 }

With this slot complete, you can test the code out by calling the slot at the end of the loadThumbs() slot:

 uploadFiles();

With this line added, whenever you load a album into LXFGallery, the slot will be run and you will see the progress dialog appear as the files are transferred to the FTP server.

Release your work


If you're going to be writing software for release, particularly if the software is going to be open source software available on the internet, you should spend some time getting your software cleaned up into a fit state to release publicly. Even source code needs to be presented in a state that's simple and easy to use.

The first step is to clean out all of the object code in your source directory so that these half-compiled chunks of data are not included in your source release. To do this, run the following command in the base of your source code directory:

make dist-clean

The next step is to write some important files to be included with your code. You may have seen that there are README and INSTALL text files included with the source. In the README file you should add some information about your program, and most importantly, your email and possibly a web address for the program. This will be essential when people want to send you patches and improvements to your program that you can merge into it.

The INSTALL file that is included with the LXFGallery source code provides generic instructions for compiling the software, but you may prefer to write more specific instructions for your particular program. A final file you should include is a LICENSE file. This file contains a copy of the the license you have chosen for your program. With the code ready to be zipped up, you can tar and zip it with:

tar zcvf myprogram.tgz programsourcecode/

This will create a myprogram.tgz archive with your source code release. You may now want to rename this so that the version number is included in the filename:

mv myprogram.tgz myprogram-v1.0.tgz

This makes it easier for your users to understand which version of the program they have downloaded.


Moving forward


KDE programming is a large and complex subject, and in this series we have covered the major chunks of code that are needed to get you started. Although this has got us to a point where you can write a full and complete program, it's likely that you will need to explore some of the other components in the KDE system. To give you an overview of where to get started, here is a summary of some of the most important technologies:

KParts This is a component framework for embedding programs inside one another. A typical example of a component is when you want to insert a spreadsheet inside a word processor document in your office suite. In most cases, you insert one of these objects and the window changes to an editing view that's suitable for the embedded object. Within a program such as this you would not want to reproduce all of the functionality of the spreadsheet in a separate embedded version, especially if you just want to embed the normal version inside the window. KParts provides a flexible framework for embedding components such as this, and the technology is put to good use in the KOffice suite.

DCOP The DCOP framework has been designed to enable programs to communicate and share information. Say you wanted to find out the name of the song being played in your CD player application ­ DCOP could help. You can use this information in your own program. DCOP provides an API in C++ that gives you the ability to provide hooks that expose DCOP interfaces. These can then be used by other programs. You can think of this as a similar concept to signals and slots in which you provide a series of DCOP hooks (the equivalent of slots) that other programs can connect to.

Hooked? If you'ld like to play with DCOP right now, have a look at the KDCOP program on your system; it's part of KDE, and provides a list of all the programs running on your desktop and their DCOP hooks.

KConfig XT A core requirement of any desktop environment is to be able to store the settings of your desktop and programs so that they're easily accessible. KConfig XT is the next generation of configuration management, and it provides a means for you to store program settings in the standard KDE configuration system. This gives the KDE desktop the ability to access your configuration settings in a number of different ways.

KWin and Themes KDE has a very powerful theming engine built right into the desktop. This engine has taken the theming abilities of Qt and extended them to include other features and capabilities. Within KDE, you can not only theme widgets and controls but also theme window decorations and borders. This can be useful if you want to simulate a particular environment or desktop.

If you are interested in theming, take a look at some of the themes at http://www.kde-look.org to get started.

Other application types Aside from normal desktop applications, there are a variety of other types of applications available in KDE. These include panel applets, plug-ins, control centre modules, application extensions, the KDE IO Slaves we covered and services. Each of these different types of program can be created inside KDevelop, and there are a number of pre-built templates inside the KDevelop project wizard to help you get started.

For more information on the range of Qt and KDE technologies, I'd recommended that you take a look at http://doc.trolltech.com and http://developer.kde.org. These sites provide background on the technologies available, and advice on how you can use them.

Another useful tip is to ask in one of the many IRC channels before you decide on which technology you will use to solve a particular problem, or write to one of the mailing lists (see the Further Resources box, left, for details) to see what other developers suggest as the best way to solve the problem. There are a number of very experienced KDE developers active online, and their views and opinions can be invaluable.


The end


It's been a long trek, and if you have got this far, congratulations for sticking through the course and learning about KDE development. Any programming system has a complex set of rules and a twisted maze of concepts to learn, but with determination and practice, you can learn enough about the KDE system to write any program you want to. Take a look at the Further Resources box on the left for a list of KDE resources available online, and keep us posted on how you get on. Good luck! LXF