In my last tutorial I briefly ran through using map tools to facilitate user interaction with the map canvas. Today we will take a brief look at labelling features.
Before I carry on too far, note that QGIS's automatic labelling algorithm is very primative. Martin Dobias is planning to implement a much more useful label placement routine - but its not going to be available in QGIS 0.8. For the best label placement results you should defined fields in your attribute table for position, rotation etc of the label. Since this is only intended to be a 'get you started' introduction, I won't be doing all that here...
The entire project can be checked out form the QGIS Subversion repository using the following command:
svn co https://svn.qgis.org/repos/qgis/trunk/code_examples/3_basic_labelling
In the working directory for the tutorial code you will find a number of files including c++ sources, icons and a simple data file under data. There is also the .ui file for the main window.
Note: You will need to edit the .pro file in the above svn directory to match your system.
#include <qgslabel.h>
#include <qgslabelattributes.h>
#include <qgsfield.h>
Each vector layer can have a QgsLabel associated with it. A QgsLabel is a renderer for labels. It has a member of type QgsLabelAttributes which determines the placement (above / below / left / right etc), rotation, size, size units (points or map units), font, colour and various other elements of the label. The QgsField include is needed because we will be querying the vector layer for its available fields so that we can determine which field should be used for labelling.
In the same cpp file you will see I define a label and a label attributes pointer. These will be used to setup the labelling characteristics we want and then assigned to the layer:
QgsLabel * mypLabel;
QgsLabelAttributes * mypLabelAttributes;
Now we will see how we actually initialise and assign the QgsLabel and the QgsLabelAttributes to the vector layer.
//
//set up labelling for the layer
//
//get the label instance associated with the layer
QgsLabel * mypLabel;
mypLabel = mypLayer->label();
//and the label attributes associated with the label
QgsLabelAttributes * mypLabelAttributes;
mypLabelAttributes = mypLabel->layerAttributes();
Great now we have a handle on the QgsLabel and QgsLabelAttributes we can start to manipulate how the label will be displayed. Note that the mypLabel->layerAttributes() method is poorly named and will likely be changed (to labelAttributes()) before the final release of QGIS 1.0.
Ok next lets ask the vector layer what attribute fields it has so that we can select one to be used for labelling:
//get the field list associated with the layer
//we'll print the names out to console for diagnostic purposes
std::vector myFields = mypLayer->fields();
for (unsigned int i = 0; i < myFields.size(); i++ )
{
qDebug("Field Name: " + myFields[i].name().toLocal8Bit() );
}
By the way - you can browse the code for field, label, lable attributes etc from the QGIS source browser. Look in the 'core' and 'gui' subdirectories. Also for more implementation examples of how to set up labelling, it is worth taking a look at qgslabeldialog.cpp.
With access to the list of fields in your vector layer, you can then for example present the user with a combo box to select a label field. In this simple tutorial though I am simply going to use the last field in the attribute table. Its a bit of a no brainer because our attribute table only has one field! But at least this way its soft coded...
//just use the last field's name in the fields list as the label field!
qDebug("set label field to " + myFields[myFields.size()-1].name());
mypLabel->setLabelField( QgsLabel::Text, myFields[myFields.size()-1].name());
There are a bunch of other things we can do to manipulate the appearance of the label. Lets set the text colour to black and draw a yellow 1 point 'halo' buffer around it so the label won't get lost when there are black features behind it:
//set the colour of the label text
mypLabelAttributes->setColor(Qt::black);
//create a 'halo' effect around each label so it
//can still be read on dark backgrounds
mypLabelAttributes->setBufferEnabled(true);
mypLabelAttributes->setBufferColor(Qt::yellow);
int myType = QgsLabelAttributes::PointUnits;
mypLabelAttributes->setBufferSize(1,myType);
Finally we need to tell the layer that rendering of labels should be enabled:
mypLayer->setLabelOn(true);For the absolute best labelling results, I advise you to store all the label properties you can inside your attribute table. Doing this will allow you to set rotation, placement etc on a per label basis. I left some comments in the tutorial source code that will get you started with this:
/*
* Here are a bunch of other things you can set based on values on a database field
* the second parameter in each case would be the field name from which the
* attribute can be retrieved.
mypLabel->setLabelField( QgsLabel::Family, "fontFamily" );
mypLabel->setLabelField( QgsLabel::Bold, "fontIsBold" );
mypLabel->setLabelField( QgsLabel::Italic, "fontIsItalic" );
mypLabel->setLabelField( QgsLabel::Underline, "fontIsUnderlined" );
mypLabel->setLabelField( QgsLabel::Size, "fontSize" );
mypLabel->setLabelField( QgsLabel::BufferSize,"fontBufferSize" );
mypLabel->setLabelField( QgsLabel::XCoordinate, "labelX" );
mypLabel->setLabelField( QgsLabel::YCoordinate, "labelY");
mypLabel->setLabelField( QgsLabel::XOffset, "labelXOffset");
mypLabel->setLabelField( QgsLabel::YOffset, "labelYOffset");
mypLabel->setLabelField( QgsLabel::Alignment, "labelAlignment" );
mypLabel->setLabelField( QgsLabel::Angle, "labelAngle");
*/
Well that wraps up this tutorial. One thing I noticed is that the canvas is not refreshing properly sometimes on the mac unless you cover the application briefly with another window. Ill post an update here if I figure out what is causing this.
mkdir -p qgis_example3.app/Contents/MacOS/share/qgis/resources/
cp -r /Applications/qgis.app/Contents/MacOS/share/qgis/resources/* \
qgis_example3.app/Contents/MacOS/share/qgis/resources/