QGeoMapCustomObject Class Reference

Detailed Description

The QGeoMapCustomObject class is a QGeoMapObject used to draw a QGraphicsItem on a map.

Any arbitrary QGraphicsItem can be associated with a QGeoMapCustomObject, and to this end it contains support for interpreting the coordinates of the QGraphicsItem in a variety of different ways.

For example, the following code creates a QGraphicsEllipseItem and a QGeoMapCustomObject to display it. The EllipseItem extends from the origin point, out 20 meters to the east and 30 metres south.

 QGraphicsEllipseItem *ellipseItem = new QGraphicsEllipseItem;
 ellipseItem->setRect(0, 0, 20, 30);

 QGeoMapCustomObject *mapObject = new QGeoMapCustomObject;
 mapObject->setGraphicsItem(ellipseItem);
 mapObject->setUnits(QGeoMapObject::MeterUnit);
 mapObject->setOrigin(QGeoCoordinate(-27.5796, 153.1));

Units and coordinates

The local units and coordinates of the QGraphicsItem are transformed onto the map based on the units, origin, transformType and transform properties. Several systems are available, including pixels, meters and seconds of arc.

It should be noted that both pixel and meter coordinate systems are south- oriented (ie, positive Y axis faces south on the map). However, the RelativeArcSeconds unit system faces north to align with the standard latitude grid. The Y axis can be flipped if necessary by making use of the GraphicsItem's transform property

 QTransform northFlip;
 northFlip.scale(0, -1);

 ellipseItem->setTransform(northFlip);

Transform methods

Normally, the GraphicsItem will be transformed into map coordinates using a bilinear interpolation. Another option is the ExactTransform, which converts the GraphicsItem exactly into map coordinates, but is only available for certain subclasses of QGraphicsItem. Other interpolation methods may be provided in future for greater accuracy near poles and in different map projections, without the limitations of ExactTransform.

Calling setUnits() or setting the units property will result in the default value of transformType being restored. See QGeoMapObject::transformType for more details.

Caveats

Other than the coordinate system features, there are a few differences with using QGraphicsItems on a map compared to using them on a standard QGraphicsScene. One of the most important of these is the use of the update() function. When an application changes anything that has an effect upon the appearance, size, shape etc of the QGraphicsItem, it must call QGeoMapCustomObject::update() to ensure that the map is updated.

Another is the use of child items of a QGraphicsItem. These are supported in more or less the same manner as in QGraphicsScene, with the exception of use in concert with ExactTransform -- any object with transformType set to ExactTransform will not have children of its QGraphicsItem drawn on the map.