digiKam Developer Documentation: Digikam::MapWidget Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Digikam::MapWidget Class Reference

The central map view class of geolocation interface. More...

Inheritance diagram for Digikam::MapWidget:

## Public Member Functions
| MapWidget (QWidget *const parent=nullptr)
| ~MapWidget () override

## Appearance
void | setSortKey (const int sortKey)
void | setThumnailSize (const int newThumbnailSize)
void | setThumbnailGroupingRadius (const int newGroupingRadius)
void | setMarkerGroupingRadius (const int newGroupingRadius)
int | getThumbnailSize () const
int | getUndecoratedThumbnailSize () const
void | setShowThumbnails (const bool state)
QString | convertZoomToBackendZoom (const QString &someZoom, const QString &targetBackend) const
void | getColorInfos (const int clusterIndex, QColor *fillColor, QColor *strokeColor, Qt::PenStyle *strokeStyle, QString *labelText, QColor *labelColor, const GeoGroupState *const overrideSelection=nullptr, const int *const overrideCount=nullptr) const
| Return color and style information for rendering the cluster.
void | getColorInfos (const GeoGroupState groupState, const int nMarkers, QColor *fillColor, QColor *strokeColor, Qt::PenStyle *strokeStyle, QString *labelText, QColor *labelColor) const
void | slotShowThumbnailsChanged ()
void | slotZoomIn ()
void | slotZoomOut ()
void | slotDecreaseThumbnailSize ()
void | slotIncreaseThumbnailSize ()
void | stopThumbnailTimer ()
void | signalRemoveCurrentFilter ()
void | signalStickyModeChanged ()

## Settings Management related functions
void | saveSettingsToGroup (KConfigGroup *const group)
void | readSettingsFromGroup (const KConfigGroup *const group)
void | slotItemDisplaySettingsChanged ()

## Map related functions
QStringList | availableBackends () const
bool | setBackend (const QString &backendName)
QList< MapBackend * > | backends () const
GeoCoordinates | getCenter () const
void | setCenter (const GeoCoordinates &coordinate)
void | setZoom (const QString &newZoom)
QString | getZoom ()
void | adjustBoundariesToGroupedMarkers (const bool useSaneZoomLevel=true)
| Adjusts the visible map area such that all grouped markers are visible.
void | refreshMap ()
void | setRegionSelection (const GeoCoordinates::Pair &region)
GeoCoordinates::Pair | getRegionSelection ()
void | clearRegionSelection ()
void | updateMarkers ()
void | updateClusters ()
void | markClustersAsDirty ()
QPixmap | getDecoratedPixmapForCluster (const int clusterId, const GeoGroupState *const selectedStateOverride, const int *const countOverride, QPoint *const centerPoint)
QVariant | getClusterRepresentativeMarker (const int clusterIndex, const int sortKey)
void | slotBackendReadyChanged (const QString &backendName)
void | slotChangeBackend (QAction *action)
void | slotBackendZoomChanged (const QString &newZoom)
void | slotClustersMoved (const QIntList &clusterIndices, const QPair< int, QModelIndex > &snapTarget)
void | slotClustersClicked (const QIntList &clusterIndices)
void | slotLazyReclusteringRequestCallBack ()
| Helper function to buffer reclustering.
void | slotRequestLazyReclustering ()
| Request reclustering, repeated calls should generate only one actual update of the clusters.
void | slotRemoveCurrentRegionSelection ()
void | slotNewSelectionFromMap (const Digikam::GeoCoordinates::Pair &sel)
bool | currentBackendReady () const
void | applyCacheToBackend ()
void | saveBackendToCache ()
void | setShowPlaceholderWidget (const bool state)
void | setMapWidgetInFrame (QWidget *const widgetForFrame)
| Set `widgetForFrame` as the widget in the frame, but does not show it.
void | removeMapWidgetFromFrame ()
void | slotClustersNeedUpdating ()
void | signalRegionSelectionChanged ()

## Data Management
void | addUngroupedModel (GeoModelHelper *const modelHelper)
void | removeUngroupedModel (GeoModelHelper *const modelHelper)
void | setGroupedModel (AbstractMarkerTiler *const markerModel)
void | setDragDropHandler (GeoDragDropHandler *const dragDropHandler)
void | setTrackManager (TrackManager *const trackManager)
void | slotUngroupedModelChanged ()
void | signalLoadTracksFromAlbums ()
void | signalUngroupedModelChanged (const int index)

## UI setup
QAction * | getControlAction (const QString &actionName)
QWidget * | getControlWidget ()
| Returns the control widget instance.
void | addWidgetToControlWidget (QWidget *const newWidget)
void | setSortOptionsMenu (QMenu *const sortMenu)
void | setMouseMode (const GeoMouseModes mouseMode)
void | setAvailableMouseModes (const GeoMouseModes mouseModes)
void | setVisibleMouseModes (const GeoMouseModes mouseModes)
void | setAllowModifications (const bool state)
void | setActive (const bool state)
bool | getActiveState ()
bool | getStickyModeState () const
void | setStickyModeState (const bool state)
void | setVisibleExtraActions (const GeoExtraActions actions)
void | setEnabledExtraActions (const GeoExtraActions actions)
void | slotMouseModeChanged (QAction *triggeredAction)
void | rebuildConfigurationMenu ()
void | createActions ()
void | createActionsForBackendSelection ()
void | dropEvent (QDropEvent *event) override
void | dragMoveEvent (QDragMoveEvent *event) override
void | dragEnterEvent (QDragEnterEvent *event) override
void | dragLeaveEvent (QDragLeaveEvent *event) override
void | slotUpdateActionsEnabled ()
void | slotStickyModeChanged ()
void | signalMouseModeChanged (const Digikam::GeoMouseModes &currentMouseMode)

## Detailed Description

The MapWidget class is the central widget of geolocation interface. It provides a widget which can display maps using either the Marble or Google Maps backend. Using a model, items can be displayed on the map. For models containing only a small number of items, the items can be shown directly, but for models with a larger number of items, the items can also be grouped. Currently, any number of ungrouped models can be shown, but only one grouped model. Item selection models can also be used along with the models, to interact with the selection states of the items on the map. In order to use a model with geolocation interface, however, a model helper has to be implemented, which extracts data from the model that is not provided by the Qt part of a model's API.

Now, a brief introduction on how to get geolocation interface working is provided:

- First, an instance of `MapWidget` has to be created.
- Next, `GeoModelHelper` has to be subclassed and at least the pure virtual functions have to be implemented.
- To show the model's data ungrouped, the model helper has to be added to `MapWidget` instance using addUngroupedModel.
- To show the model's data grouped, an instance of `AbstractMarkerTiler` has to be created and the model helper has to be set to it using setMarkerGeoModelHelper. The `AbstractMarkerTiler` has then to be given to MapWidget using setGroupedModel. If the items to be displayed do not reside in a model, a subclass of `AbstractMarkerTiler` can be created which returns just the number of items in a particular area, and picks representative items for thumbnails.
- To handle dropping of items from the host applications UI onto the map, `DragDropHandler` has to be subclassed as well and added to the model using setDragDropHandler.
- Finally, setActive() has to be called to tell the widget that it should start displaying things.

## Constructor & Destructor Documentation

## ◆ ~MapWidget()

Digikam::MapWidget::~MapWidget | ( |  | ) |
| override

## Member Function Documentation

## ◆ addUngroupedModel()

void Digikam::MapWidget::addUngroupedModel | ( | GeoModelHelper *const | modelHelper | ) |

## ◆ adjustBoundariesToGroupedMarkers()

void Digikam::MapWidget::adjustBoundariesToGroupedMarkers | ( | const bool | useSaneZoomLevel = `true` | ) |

Note that a call to this function currently has no effect if the widget has been set inactive via setActive() or the backend is not yet ready.

Parameters

  useSaneZoomLevel | Stop zooming at a sane level, if markers are too close together.

## ◆ applyCacheToBackend()

void Digikam::MapWidget::applyCacheToBackend | ( |  | ) |
| protected

## ◆ convertZoomToBackendZoom()

QString Digikam::MapWidget::convertZoomToBackendZoom | ( | const QString & | someZoom,
|  | const QString & | targetBackend
| ) |  | const

## ◆ dragEnterEvent()

void Digikam::MapWidget::dragEnterEvent | ( | QDragEnterEvent * | event | ) |
| overrideprotected

## ◆ getColorInfos() [1/2]

void Digikam::MapWidget::getColorInfos | ( | const GeoGroupState | groupState,
|  | const int | nMarkers,
|  | QColor * | fillColor,
|  | QColor * | strokeColor,
|  | Qt::PenStyle * | strokeStyle,
|  | QString * | labelText,
|  | QColor * | labelColor
| ) |  | const

## ◆ getColorInfos() [2/2]

void Digikam::MapWidget::getColorInfos | ( | const int | clusterIndex,
|  | QColor * | fillColor,
|  | QColor * | strokeColor,
|  | Qt::PenStyle * | strokeStyle,
|  | QString * | labelText,
|  | QColor * | labelColor,
|  | const GeoGroupState *const | overrideSelection = `nullptr`,
|  | const int *const | overrideCount = `nullptr`
| ) |  | const

Parameters

  clusterIndex | Index of the cluster
  fillColor | Color used to fill the circle
  strokeColor | Color used for the stroke around the circle
  strokeStyle | Style used to draw the stroke around the circle
  labelText | Text for the label
  labelColor | Color for the label text
  overrideSelection | Get the colors for a different selection state
  overrideCount | Get the colors for a different amount of markers

## ◆ getDecoratedPixmapForCluster()

QPixmap Digikam::MapWidget::getDecoratedPixmapForCluster | ( | const int | clusterId,
|  | const GeoGroupState *const | selectedStateOverride,
|  | const int *const | countOverride,
|  | QPoint *const | centerPoint
| ) |  |

## ◆ removeUngroupedModel()

void Digikam::MapWidget::removeUngroupedModel | ( | GeoModelHelper *const | modelHelper | ) |

## ◆ setBackend()

bool Digikam::MapWidget::setBackend | ( | const QString & | backendName | ) |

## ◆ setGroupedModel()

void Digikam::MapWidget::setGroupedModel | ( | AbstractMarkerTiler *const | markerModel | ) |

## ◆ setSortKey()

void Digikam::MapWidget::setSortKey | ( | const int | sortKey | ) |

## ◆ setThumnailSize()

void Digikam::MapWidget::setThumnailSize | ( | const int | newThumbnailSize | ) |

## ◆ slotClustersClicked

void Digikam::MapWidget::slotClustersClicked | ( | const QIntList & | clusterIndices | ) |
| protectedslot

## ◆ slotClustersMoved

void Digikam::MapWidget::slotClustersMoved | ( | const QIntList & | clusterIndices,
|  | const QPair< int, QModelIndex > & | snapTarget
| ) |  |
| protectedslot

## ◆ slotItemDisplaySettingsChanged

void Digikam::MapWidget::slotItemDisplaySettingsChanged | ( |  | ) |
| protectedslot

## ◆ slotMouseModeChanged

void Digikam::MapWidget::slotMouseModeChanged | ( | QAction * | triggeredAction | ) |
| protectedslot

## ◆ slotNewSelectionFromMap

void Digikam::MapWidget::slotNewSelectionFromMap | ( | const Digikam::GeoCoordinates::Pair & | sel | ) |
| protectedslot

## ◆ slotUpdateActionsEnabled

void Digikam::MapWidget::slotUpdateActionsEnabled | ( |  | ) |
| slot

## ◆ updateClusters()

void Digikam::MapWidget::updateClusters | ( |  | ) |