18.3. Getting Started with the KDE 2.0 API

The main issue for a programmer who wants to write an application using libraries such as Qt and the extensions offered by KDE is where to get the information about the interfaces (the classes of the libraries) and how to use them. This is a special area where KDevelop gives you a great help, even if you choose to use a different programming environment for writing your application. Long-term emacs users, for example, might prefer to stay with their editor and write their framework themselves.

First let's look at what KDevelop offers in documentation availability:

  • KDevelop ships with five handbooks in HTML format that are available for online reading and that can also be printed out using the sgmltools on the SGML files that come with the source code of KDevelop. These handbooks contain a user manual describing the whole IDE and its features, as well as an introduction to development in general, a programming handbook for KDE development, and a tutorial handbook with a guide showing how to create and run KDE/Qt applications with KDevelop (including a step-by-step introduction to using the KDE API to create a sample project and the source code of the sample program). Furthermore, the book The KDE Library Reference Guide contains detailed explanations about the Qt signal/slot mechanism, an explanation of the event loop of a GUI-based application, event-handling implementation and manipulation, as well as a description of the commonly used KDE classes. Finally, the KDE 2.0 Developer's Guide introduces the developer to some principles and guidelines toward targeting KDE 2.0 application development. The IDE also contains a complete C/C++ reference that will assist the developer in certain questions about the C and C++ programming languages.

  • Within KDevelop, you can generate the complete KDE API with the help of KDOC via the Setup (you may choose to generate it for KDE 1.x or KDE 2.0, whatever system you want to develop for). This includes the KDE standard libraries, the KDE base libraries (kcontrol and libkonq) for writing modules to extend Konqueror or the KDE Control Center, as well as the KOffice libraries used to create KOffice applications. You can regenerate the API documentation any time you want, especially if the API has changed or has been extended. This is a good way to get the newest set of information available. In addition, the documentation is cross-referenced with the Qt online API documentation that comes with the distribution of the Qt library. Therefore, you have full access to the inheritance structure and can easily look up relationships between KDE and Qt.

  • KDevelop allows you to make search requests over the complete documentation on your system. To enable this, the system needs to have a search engine installed (available are htdig or glimpse for use with KDevelop). The search engines contain an indexing function to create a search database that it will use to look up your request and build up the results that will then be displayed as an HTML page in the documentation browser. The required indexing can be done easily via a graphical interface available in the KDevelop setup.

  • KDevelop contains a documentation browser that offers direct access to the API and that works in conjunction with the documentation tree described previously. The documentation tree displays all libraries and user documentation as books containing chapters; for libraries, these are the classes that again can be unfolded to list all methods of a class and that will bring you directly where you need to go—the documentation to the exact method you want to use. Retrieving the information you need is not a matter of browsing through header files on the system, nor is it a matter of organizing bookmarks for each library in your favorite browser. With KDevelop's browsing facilities, you have the best available access to the API that you need to have to successfully develop your application within a reasonable timeframe (see Figure 18.6).

Figure 18.6. The KDevelop Documentation-Browser with the Tree View displaying the KDE 2.0 API down to the member functions of classes.

18.3.1. How to Search for Information

KDevelop provides several ways to look up information about keywords, classes, or generally anything of interest to the developer that could be explained somewhere in the documentation. At first, looking up used methods within the source code can be done by setting the cursor into the method's name and then pressing the right mouse button and selecting Search: expression. The search engine will then look up the desired information, switch to the Documentation-Browser, and display a results page containing a preview of the first result of each page. You can then select which search result seems to have the information you want—just like searching on the Internet with a search engine such as Yahoo!.

When you're switching to one result, the found expression is automatically highlighted for you. For looking up the next expression on the same page matching your search, you could use the F3 shortcut or from the View menu of KDevelop, select Repeat Search.

Other possibilities to look up expressions are

  • The Search for Help On dialog, available from the Help menu. This dialog allows you to enter the search expression.

  • Within the Documentation-Browser, you can mark text that can then be looked up with the context menu, the same as described for the editor window.

  • Selecting text and using the Help menu item Search Marked Text or the appropriate shortcut to call this function.

You'll surely like these features within KDevelop because the amount of documentation grows with the extending of the KDE/Qt API, and it would be very hard to find the functions you need if you don't know exactly which one to use or whether that functionality is provided by the libraries at all.