Next Previous Table of Contents
Most of KDevelop's strength is accumulated in the Help System. It is also to be understood as an example of how to extend your own KDE application with a complete set of help functionality, and is, in part, already realized in the template applications, so KDE/Qt application frameworks generated with the KAppWizard do already contain the basic functionality for statusbar help and documentation, that only has to be extended by the programmer. This section therefore introduces into the usage of the general help provided within the IDE as well as to show the usage of the Helpbrowser, which, by intelligent use, will make it very easy to get the information you need for development.
Looking at KDevelop's top toolbar, you will see the "What's this?" button on the right end. By selecting the button, the cursor will change to a pointer with a question mark on the right, as is the same as the button in the toolbar. Now, you can select any visible part of the KDevelop user interface and click on it. This will result in displaying a help-window giving you a short description of the function this part gives you or what it can do for you. Included are the main view, the tree-views and the toolbars, for which every button help is provided. After another mouse click or a keyboard input, the What's this? help window disappears and your cursor is set to the last active position. Mind, that, if you place the mouse pointer over a button, it gets raised and after a short time, you will get a Quick-Tip-window, describing the function the button represents in the menubar; this will disappear if you move the mouse pointer away.
For user interaction dialogs, Quickhelp provides you help windows with a short description of the selected item you want help for. These are accessed by a right-button mouse click to the item, a context-menu pops up that allows the selection of "Quick-Help". Selecting this will pop up the help window. This is always useful for dialogs where you can't see the action's purpose for as long as you are not familiar with KDevelop. Mind that most dialogs offer a Help-button which will show you the detailed context-help for the dialog's options within the provided online-manual in the help-browser.
The statusbar of KDevelop offers you many functions that inform you about the current activity state as well as "status messages" offering a short description for commands.
The Statusbar contains:
The statusbar informs you about the action of menu entries if you select a menu within the menubar and select an action without executing it. Further, if you press on a toolbar icon, but without releasing the mousebutton, the help message for the button is displayed in the same way as for the menu entries. You can prevent the execution of the selected icon by moving the mousepointer away from the icon, still holding the button pressed. If the cursor is away, release the mousebutton.
For actions that are currently executed, KDevelop displays the action. This counts for processes running in the background such as saving files as well as for dialogs. If the process has exited such as a make-invocation, the statusbar display changes back to "Ready" state.
Also, when using the documentation browser, the statusbar displays link urls for as long as the cursor is placed over an URL link in the browser window. Therefore, you can easily find out if the file is a local or a remote file only accessed by network connection.
The caption of the KDevelop Project Editor shows you the currently opened filename in the top window. This would be a HTML file for the documentation browser or a text file for the editing windows. Further, the Project name is displayed, so you have constant control where you are and what you're currently working at.
The browser included in KDevelop is completely HTML-based, therefore you can specify the usual options like background and the like. You can set all preferences by the "Documentation Browser"-entry of the "Options"-menu. The configuration dialog shows you two tabulators; the first for setting the font preferences, the second for color selection.
The first option for the font display is the size. Available are small, medium and large. The best display for normal use is set to small by default. For the font selection you have to specify a standard font for normal text as it appears in HTML documents; the fixed font is the one used for displaying e.g. code within the HTML file.
The color preferences dialog allows configuration of background, normal text, URL Link and followed link color. The colored buttons on the right are displaying the current settings; selecting a button will result in opening the "Select Color" dialog. There, you can specify the color either by choosing a System Color, a custom color, select the color by the multi-colored window or by setting the values directly. The middle contains a preview for the color selected.
Further, you can specify if the browser should underline links to easier detect them visually and if you like to use your own colors always independent of the page's preset ones. "Apply" will execute all changes, while "OK" will apply changes and close the dialog. "Cancel" leaves all settings untouched and exits the configuration.
The documentation browser allows quick and easy access to all manuals and documentations that are provided with KDevelop or generated automatically, including online-documentation for the KDE-libraries and your project documentation. Plus, the Documentation Tree in the tree-view lets you customize a special "Others" folder that contains all individually added documentation.
To make use of all features of the Helpbrowser, you should have KDoc and glimpse installed. KDoc will generate all kind of online class-documentation for the KDE-libraries during the setup process, but can also invoked by option in the KDevelop Setup. For the generation of an API (Application Programming Interface) Documentation for your project's classes, KDoc is also used and called by the Project-menu, entry "Make API-Doc". This will process all current header files of the project plus the addition of a cross-reference to the Qt and KDE-libraries if those are available in the Helpbrowser. For the generation of the project handbooks, you should have KSgml2Html (provided with the KDE-SDK) and, as a minimum, SGML-tools installed on your system. To extend and change your project's online-documentation, you have to edit the documentation file for your project by selecting it in the RFV. After saving your changes, call "Make User-Manual" from the Project-menu. In case SGMLtools detect formatting errors, those will be displayed in the output window allow you to find the error line directly. The program "glimpse" is used to create a personal search-index for your documentation automatically. The index is generally build during the installation process, but can also be build with the KDevelop Setup dialog. For a description of the provided search functions see Using the Searchindex.
The KDevelop IDE comes with two sets of online-documentation, which can be accessed either via the Help-menu or by the Doc-tree in the Tree-View in the KDevelop folder. The first book provided is this online-handbook containing all information you need towards installation, configuration, available functionality and introduction to application development. The second book is The KDevelop Programming Handbook in it's first edition. The programming handbook covers most questions related to the creation and extension of projects that work with KDevelop. By tutorials the user gets an introduction to the rich facilities that applications created with the Qt- and/or KDE-libraries have to offer as well as given a guideline for ensuring KDE-compliance, which covers the same instructions given on the Internet site at http://developer.kde.org. However, the programming handbook cannot replace any additional documentation available in printed or electronic form about the C++ programming language as well as about the usage of the Qt-library in certain terms.
The C/C++-Reference used with KDevelop is currently only available on the KDevelop homepage at
http://www.kdevelop.org. On distributions the reference may be included, see your distribution installation program index for
more information. It can be installed easily by downloading and copying the sourcefile to the main KDE-directory ($KDEDIR). There, you
have to untar it as root with tar zxvf c_c++_reference.tar.gz, the reference will then be copied the documentation directory of
KDevelop. For uninstalling the reference documentation you just have to delete the "reference" folder under
($KDEDIR)/share/doc/HTML/default/kdevelop/reference.
The Qt/KDE-libraries documentation folder allows direct access to the HTML-online documentation of your copy of the Qt-library. The path to the library documentation is usually automatically detected by the KDevelop installation program, but can be set manually in the KDevelop Setup dialog. Also, all available documentation for the KDE-libraries are listed in order of the library name, so if you would use classes of a certain library it is easy to determine the library type to be added to the Linker settings in the project. Mind that the whole KDE-Library documentation is only accessible when generated by KDoc- so this program, included in the KDE-SDK, has to be installed before the documentation can be generated. As the installation program of KDevelop does this automatically, it should be installed before running the KDevelop Setup. If this is not the case and the documentation cannot be build, you are able to create it afterwards at any time with the KDevelop Setup dialog.
The documentation tree also contains the "Others" folder which is intended to contain all personally customized documentation as described below. Finally, the Doc-Tree allows access to the API and the Manual for your current project.
To customize your Helpbrowser, open the Tree-View and select the "DOC" Tabulator. You will see an opened tree containing four folders. The "Others" folder is, by default, empty. On a right mousebutton click over this folder, a context menu opens that has an entry "Add Entry". Select this to open the Add Entry dialog where you have to enter two values: the upper one for the name that will be displayed for the documentation within the Doc-tree, and, below that, a file-entry line. Here, you have to enter the path and filename to the start page that will be opened by the selection of the entry later. You can enter the path and filename directly or by selection of the pushbutton on the right to open a file-chooser dialog. This allows a quick browsing on your system to the path for your start page. Mind that only HTML-documentation can be selected, so only HTML files are allowed to choose. Selecting OK will add the entry to the Doc-tree and is available directly.
KDevelop includes a set of functions to help you search information within HTML documentation. To use these features, your system needs to have the program "glimpse", a free database generator, installed, which creates the search index and executes searches within the documentation. To set up the index, see KDevelop Setup. The index is also automatically generated during the installation program.
The search functions are available through several ways which you can choose from:
The Helpbrowser also offers support for grep to search for a selection within your current project, e.g you've opened the documentation
page for the KTMainWindow class (KDEUI library) and you want to know where in your code KTMainWindow appears. Mark
KTMainWindow and either select "Grep: KTMainWindow" or press Shift+F2. The "Search in Files" dialog opens with the results about
your grep search directly. Then you can choose an result line to jump to the according sourcecode.
Next Previous Table of Contents