Deciphering the C++ documentation

As QGIS is implemented in C++, the documentation for QGIS APIs is all based on C++. This can make it difficult for Python developers to understand and work with the QGIS APIs. For example, the API documentation for the QgsInterface.zoomToActiveLayer() method:

If you're not familiar with C++, this can be quite confusing. Fortunately, as a Python programmer, you can skip over much of the complexity as it doesn't apply to you. In particular:

Just like in Python, the parentheses show that the method doesn't take any parameters. So if you have an instance of QgisInterface (for example, as the standard iface variable available in the Python Console), you can call this method simply by typing the following:

iface.zoomToActiveLayer()

Now, let's take a look at a slightly more complex example: the C++ documentation for the QgisInterface.addVectorLayer() method looks like the following:

Notice how the virtual keyword is followed by QgsVectorLayer* instead of void. This is the return value for this method; it returns a QgsVector object.

Notice the brief description at the bottom of the documentation for this method; while many of the C++ methods have very little, if any, additional information, other methods have more extensive information. Obviously, you should read these descriptions carefully as they tell you more about what the method does.

Even without any description, the C++ documentation is still useful as it tells you what the method is called, what parameters it accepts, and what type of data is being returned.

In the preceding method, you can see that there are three parameters listed in between the parentheses. As C++ is a strongly typed language, you have to define the type of each parameter when you define a function. This is helpful for Python programmers as it tells you what type of value to supply. Apart from QGIS objects, you might also encounter the following data types in the C++ documentation:

Just as in Python, a method can take default values for each parameter. For example, the QgisInterface.newProject() method looks like the following:

In this case, the thePromptToSaveFlag parameter has a default value, and this default value will be used if no value is supplied.

In Python, classes are initialized using the __init__ method. In C++, this is called a constructor. For example, the constructor for the QgsLabel class looks like the following:

Just as in Python, C++ classes inherit the methods defined in their superclass. Fortunately, QGIS doesn't have an extensive class hierarchy, so most of the classes don't have a superclass. However, don't forget to check for a superclass if you can't find the method you're looking for in the documentation for the class itself.

Finally, be aware that C++ supports the concept of method overloading. A single method can be defined more than once, where each version accepts a different set of parameters. For example, take a look at the constructor for the QgsRectangle class—you will see that there are four different versions of this method.

The first version accepts the four coordinates as floating point numbers:

The second version constructs a rectangle using two QgsPoint objects:

The third version copies the coordinates from QRectF (which is a Qt data type) into a QgsRectangle object:

The final version copies the coordinates from another QgsRectangle object:

The C++ compiler chooses the correct method to use based on the parameters that have been supplied. Python has no concept of method overloading; just choose the version of the method that accepts the parameters you want to supply, and the QGIS Python wrappers will automatically choose the correct method for you.

If you keep these guidelines in mind, deciphering the C++ documentation for QGIS isn't all that hard. It just looks more complicated than it really is, thanks to all the complexity specific to C++. However, it doesn't take long for your brain to start filtering out the C++ gobbledygook, and you'll be able to use the QGIS reference documentation almost as easily as if it was written for Python rather than C++.