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::vectorBy 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...myFields = mypLayer->fields(); for (unsigned int i = 0; i < myFields.size(); i++ ) { qDebug("Field Name: " + myFields[i].name().toLocal8Bit() ); }
//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/