{{Warning|The functionaly described here requires an unreleased version of KDevelop. If you are not using the latest development version, while you can write class templates, you will not be able to use them.}}

{{TutorialBrowser|

{{TutorialBrowser|

Latest revision as of 13:48, 11 July 2012

Under Construction

This is a new page, currently under construction!

Warning

The functionaly described here requires an unreleased version of KDevelop. If you are not using the latest development version, while you can write class templates, you will not be able to use them.

In this tutorial, we will create a template for a basic C++ class. It will demonstrate using the Grantlee template language, as well features specific to KDevelop class templates.

We chose C++ because even the simplest class definition often consists of two separate files, header and implementation. It is possible to include any number of files in a class template (there should be at least one, obviously).

There is a project template for a C++ class template available here. The resulting project is similar to what we will create here. You may use it to create the files but still follow this tutorial for explanation.

We will start with an empty directory. Name it something unique, like kdev_class_tutorial.

Every class template needs a description file. It is a regular desktop file with an extension of .desktop. Its base name must match the name of the generated archive, so let's call it kdev_class_tutorial.desktop. Paste in these contents:

[General]Name=TutorialComment=An example C++ class template, suitable for a tutorialCategory=C++Files=Header,Implementation[Header]Name=HeaderFile=class.hOutputFile={{ name }}.h[Implementation]Name=ImplementationFile=class.cppOutputFile={{ name }}.cpp

You can see there are three sections in the description file: one for general properties, and one for each output file. In order for a file to be generated, it has to be listed in the Files entry, as well as have its own section with the same name.

In the output file sections, we already used template variables: {{ name }} will be replaced with the class name. The actual generated header file will not be {{ name }}.h, but rather Exmample.h, assuming we name our class Example.

In most free software projects, source files start with a license header. This header varies with the chosen license, author, and the programming language's comment characters. When using our template, the user choose one of the suggested licenses or write his own. In either case, the full text of the license header is available to the template as the license variable.

Since C++ has block-style comments, we could write the license simply as

/*
{{ license }}
*/

However, it might be easier to read if the license had some kind of formatting. For this purpose, KDevPlatform includes a template filter library that makes it possible to write a nicely-formatted license header. We can use it like this:

{% load kdev_filters %}/*
{{ license|lines_prepend:" * " }}
*/

The lines_prened filter prepends its argument (in our case " * ") to every line of its input (in our case the license). This can produce licenses like the following

If our file is to be included somewhere, it is good practice to provide an include guard macro. KDevPlatform ships a convenience template for generating such a macro called include_guard_cpp.txt. We can use it like this

The included template will expand into an uppercase class name with an appended _H, which could also be achieved by typing {{ name|upper }}_H. However, the include guard template also supports namespaces.

Information about inheritance is stored in the baseClasses variable. It is a list that can be iterated using a for loop. Each list element has two properties, inheritanceMode and baseType, which can be accessed using the dot notation, like class members in C++ or Python.

If our new class inherites from KFoo and KBar, and both inheritances are public, the output from such a template looks like

class Example
: public KFoo, public KBar
{

The template text could also be written in one line, so that the inheritance declarations (as possible the opening brace) would be on the same line as the class name. It is only written out this way in the tutorial for better readability. Both versions are valid C++.

Every function in C++ has a return type, if it returns nothing that type is void, which is what the default filter assures. Next, we have included another templates, called arguments_types_names.txt, which creates an argument list for language that require both argument types and names to be specified. This template requires a variables called arguments, which we created within the {% with %} statement.

Class implementation has the same license as the header, and needs no include guard. Instead, it has to include the header file and contain bodies for member functions.

Including the header can be done using variables. For every output file in the template, KDevelop adds two variables: output_file_foo with the relative path to file Foo, and output_file_foo_absolute with the absolute path. For C++ includes, we will use the relative path.

Member functions difinitions are very similar to their declarations, except that static and virtual modifiers are dropped and the class name is prepended to function names. Therefore we can copy the function declaration code and only make a small modification.