• Skip to content
• Skip to link menu

KDE 4.1 API Reference

• KDE API Reference
• kdeedu

• Sitemap
• Contact Us

 

marble/src

MarbleWidget Class Reference

#include <MarbleWidget.h>

Inheritance diagram for MarbleWidget:

[legend]

List of all members.

---

Detailed Description

A widget class that displays a view of the earth.

This widget displays a view of the earth or any other globe, depending on which dataset is used. The user can navigate the globe using either a control widget, e.g. the MarbleControlBox, or the mouse. The mouse and keyboard control is done through a MarbleWidgetInputHandler. Only some aspects of the widget can be controlled by the mouse and/or keyboard.

By clicking on the globe and moving the mouse, the position can be changed. The user can also zoom by using the scroll wheel of the mouse in the widget. The zoom value is not tied to any units, but is an abstract value without any physical meaning. A value around 1000 shows the full globe in a normal-sized window. Higher zoom values give a more zoomed-in view.

The MarbleWidget needs to be provided with a data model to work. This model is contained in the MarbleModel class, and it is painted by using a MarbleMap. The widget can also construct its own map and model if none is given to the constructor. A MarbleModel contains 3 separate datatypes: tiles which provide the background, vectors which provide things like country borders and coastlines and placemarks which can show points of interest, such as cities, mountain tops or the poles.

In addition to navigating with the mouse, you can also use it to get information about items on the map. You can either click on a placemark with the left mouse button or with the right mouse button anywhere on the map.

The left mouse button opens up a menu with all the placemarks within a certain distance from the mouse pointer. When you choose one item from the menu, Marble will open up a dialog window with some information about the placemark and also try to connect to Wikipedia to retrieve an article about it. If there is such an article, you will get a mini-browser window with the article in a tab.

The right mouse button controls a distance tool. The distance tool is implemented as a menu where you can choose to either create or remove so called Measure Points. Marble will keep track of the Measure Points and show the total distance in the upper left of the widget. Measure Points are shown on the map as a little white cross.

See also:

MarbleControlBox

MarbleMap

MarbleModel

Definition at line 113 of file MarbleWidget.h.

Public Slots
void	centerOn (const GeoDataPoint &point, bool animated=false)
void	centerOn (const QModelIndex &index, bool animated=false)
void	centerOn (const double &lon, const double &lat, bool animated=false)
void	centerSun ()
void	changeCurrentPosition (double lon, double lat)
void	creatingTilesStart (TileCreator *creator, const QString &name, const QString &description)
void	disableInput ()
void	enableInput ()
FileViewModel *	fileViewModel () const
void	goHome ()
GpxFileModel *	gpxFileModel ()
void	home (double &lon, double &lat, int &zoom)
Marble::MapQuality	mapQuality (Marble::ViewContext=Marble::Still)
GeoSceneDocument *	mapTheme () const
QString	mapThemeId () const
void	moveDown ()
void	moveLeft ()
void	moveRight ()
void	moveUp ()
void	notifyMouseClick (int x, int y)
void	openGpxFile (QString &filename)
Projection	projection () const
void	rotateBy (const Quaternion &incRot)
void	rotateBy (const double &deltaLon, const double &deltaLat)
void	setCenterLatitude (double lat)
void	setCenterLongitude (double lon)
void	setDownloadUrl (const QUrl &url)
void	setDownloadUrl (const QString &url)
void	setHome (const GeoDataPoint &homePoint, int zoom=1050)
void	setHome (const double lon, const double lat, const int zoom=1050)
void	setMapQuality (Marble::MapQuality, Marble::ViewContext=Marble::Still)
void	setMapThemeId (const QString &maptheme)
void	setPersistentTileCacheLimit (quint64 kiloBytes)
void	setProjection (Projection projection)
void	setProjection (int projection)
void	setPropertyValue (const QString &name, bool value)
void	setShowAtmosphere (bool visible)
void	setShowBorders (bool visible)
void	setShowCities (bool visible)
void	setShowClouds (bool visible)
void	setShowCompass (bool visible)
void	setShowElevationModel (bool visible)
void	setShowFrameRate (bool visible)
void	setShowGps (bool visible)
void	setShowGrid (bool visible)
void	setShowIceLayer (bool visible)
void	setShowLakes (bool visible)
void	setShowOtherPlaces (bool visible)
void	setShowPlaces (bool visible)
void	setShowRelief (bool visible)
void	setShowRivers (bool visible)
void	setShowScaleBar (bool visible)
void	setShowTerrain (bool visible)
void	setViewContext (Marble::ViewContext viewContext)
void	setVolatileTileCacheLimit (quint64 kiloBytes)
void	updateChangedMap ()
void	updateGps ()
void	updateRegion (BoundingBox &)
void	updateSun ()
Marble::ViewContext	viewContext () const
void	zoomIn ()
void	zoomOut ()
void	zoomView (int zoom)
void	zoomViewBy (int zoomStep)
Signals
void	distanceChanged (const QString &distanceString)
void	framesPerSecond (double fps)
void	mouseClickGeoPosition (double lon, double lat, GeoDataPoint::Unit)
void	mouseMoveGeoPosition (QString)
void	projectionChanged (Projection)
void	themeChanged (QString theme)
void	timeout ()
void	zoomChanged (int zoom)
Public Member Functions
const QRegion	activeRegion ()
void	addPlaceMarkData (const QString &data)
void	addPlaceMarkFile (const QString &filename)
double	centerLatitude () const
double	centerLongitude () const
double	distance () const
QString	distanceString () const
QList< MarbleAbstractFloatItem * >	floatItems () const
bool	geoCoordinates (const int x, const int y, double &lon, double &lat, GeoDataPoint::Unit=GeoDataPoint::Degree)
bool	globalQuaternion (int x, int y, Quaternion &q)
MarbleMap *	map () const
QPixmap	mapScreenShot ()
	MarbleWidget (MarbleMap *map, QWidget *parent=0)
	MarbleWidget (QWidget *parent=0)
int	maximumZoom () const
int	minimumZoom () const
MarbleModel *	model () const
double	moveStep ()
bool	needsUpdate () const
int	northPoleY ()
int	northPoleZ ()
quint64	persistentTileCacheLimit () const
QAbstractItemModel *	placeMarkModel () const
QItemSelectionModel *	placeMarkSelectionModel () const
Quaternion	planetAxis () const
QString	proxyHost () const
quint16	proxyPort () const
int	radius () const
bool	screenCoordinates (const double lon, const double lat, int &x, int &y)
void	setDistance (double distance)
void	setDownloadManager (HttpDownloadManager *downloadManager)
void	setInputHandler (MarbleWidgetInputHandler *handler)
void	setNeedsUpdate ()
void	setProxy (const QString &proxyHost, const quint16 proxyPort)
void	setRadius (const int radius)
bool	showAtmosphere () const
bool	showBorders () const
bool	showCities () const
bool	showClouds () const
bool	showCompass () const
bool	showElevationModel () const
bool	showFrameRate () const
bool	showGps () const
bool	showGrid () const
bool	showIceLayer () const
bool	showLakes () const
bool	showOtherPlaces () const
bool	showPlaces () const
bool	showRelief () const
bool	showRivers () const
bool	showScaleBar () const
bool	showTerrain () const
SunLocator *	sunLocator ()
quint64	volatileTileCacheLimit () const
int	zoom () const
virtual	~MarbleWidget ()
Protected Member Functions
void	connectNotify (const char *signal)
virtual void	customPaint (GeoPainter *painter)
void	disconnectNotify (const char *signal)
void	leaveEvent (QEvent *event)
void	paintEvent (QPaintEvent *event)
void	resizeEvent (QResizeEvent *)
Properties
double	latitude
double	longitude
QString	mapThemeId
quint64	persistentTileCacheLimit
int	projection
bool	showAtmosphere
bool	showBorders
bool	showCities
bool	showClouds
bool	showCompass
bool	showElevationModel
bool	showGrid
bool	showIceLayer
bool	showLakes
bool	showOtherPlaces
bool	showPlaces
bool	showRelief
bool	showRivers
bool	showScaleBar
bool	showTerrain
quint64	volatileTileCacheLimit
int	zoom

---

Constructor & Destructor Documentation

MarbleWidget::MarbleWidget

(

QWidget *

parent = 0

)

[explicit]

Construct a new MarbleWidget.

Parameters:

parent

the parent widget

This constructor should be used when you will only use one MarbleWidget. The widget will create its own MarbleModel when created.

Definition at line 118 of file MarbleWidget.cpp.

MarbleWidget::MarbleWidget	(	MarbleMap *	map,
		QWidget *	parent = 0
	)			[explicit]

Construct a new MarbleWidget.

Parameters:

	model	the data model for the widget.
	parent	the parent widget

This constructor should be used when you plan to use more than one MarbleWidget for the same MarbleModel (not yet supported, but will be soon).

Definition at line 128 of file MarbleWidget.cpp.

MarbleWidget::~MarbleWidget

(

)

[virtual]

Definition at line 139 of file MarbleWidget.cpp.

---

Member Function Documentation

const QRegion MarbleWidget::activeRegion

(

)

Return the active region in which it's possible to drag the view using the mouse.

Definition at line 798 of file MarbleWidget.cpp.

void MarbleWidget::addPlaceMarkData

(

const QString &

data

)

Add GeoDataPlacemark data as string to the model.

Parameters:

data

the string containing the PlaceMarks.

Definition at line 350 of file MarbleWidget.cpp.

void MarbleWidget::addPlaceMarkFile

(

const QString &

filename

)

Add a GeoDataPlacemark file to the model.

Parameters:

filename

the filename of the file containing the PlaceMarks.

Definition at line 344 of file MarbleWidget.cpp.

double MarbleWidget::centerLatitude

(

)

const

Return the latitude of the center point.

Definition at line 761 of file MarbleWidget.cpp.

double MarbleWidget::centerLongitude

(

)

const

Return the longitude of the center point.

Definition at line 766 of file MarbleWidget.cpp.

void MarbleWidget::centerOn	(	const GeoDataPoint &	point,
		bool	animated = false
	)			[slot]

Center the view on a point.

Parameters:

point

the point above earth from which the view can be seen by looking vertically down.

Definition at line 559 of file MarbleWidget.cpp.

void MarbleWidget::centerOn	(	const QModelIndex &	index,
		bool	animated = false
	)			[slot]

Center the view on a point.

Parameters:

index

an index for a QModel, indicating a city

Definition at line 533 of file MarbleWidget.cpp.

void MarbleWidget::centerOn	(	const double &	lon,
		const double &	lat,
		bool	animated = false
	)			[slot]

Center the view on a geographical point.

Parameters:

	lat	an angle parallel to the latitude lines +90(N) - -90(S)
	lon	an angle parallel to the longitude lines +180(W) - -180(E)

Definition at line 519 of file MarbleWidget.cpp.

void MarbleWidget::centerSun

(

)

[slot]

Definition at line 1161 of file MarbleWidget.cpp.

void MarbleWidget::changeCurrentPosition	(	double	lon,
		double	lat
	)			[slot]

Set the current Gps position.

Parameters:

	lat	the new latitude value
	lon	the new longitude value

Definition at line 993 of file MarbleWidget.cpp.

void MarbleWidget::connectNotify

(

const char *

signal

)

[protected]

Definition at line 722 of file MarbleWidget.cpp.

void MarbleWidget::creatingTilesStart	(	TileCreator *	creator,
		const QString &	name,
		const QString &	description
	)			[slot]

A slot that is called when the model starts to create new tiles.

Parameters:

	creator	the tile creator object.
	name	the name of the created theme.
	description	a descriptive text that can be shown in a dialog.

See also:

creatingTilesProgress

This function is connected to the models signal with the same name. When the model needs to create a cache of tiles in several different resolutions, it will emit creatingTilesStart once with a name of the theme and a descriptive text. The widget can then pop up a dialog to explain why there is a delay. The model will then call creatingTilesProgress several times until the parameter reaches 100 (100%), after which the creation process is finished. After this there will be no more calls to creatingTilesProgress, and the poup dialog can then be closed.

Definition at line 1060 of file MarbleWidget.cpp.

void MarbleWidget::customPaint

(

GeoPainter *

painter

)

[protected, virtual]

Enables custom drawing onto the MarbleWidget straight after.

the globe and before all other layers has been rendered.

Parameters:

painter

Definition at line 827 of file MarbleWidget.cpp.

void MarbleWidget::disableInput

(

)

[slot]

Definition at line 1184 of file MarbleWidget.cpp.

void MarbleWidget::disconnectNotify

(

const char *

signal

)

[protected]

Definition at line 730 of file MarbleWidget.cpp.

double MarbleWidget::distance

(

)

const

Return the current distance.

Definition at line 1135 of file MarbleWidget.cpp.

void MarbleWidget::distanceChanged

(

const QString &

distanceString

)

[signal]

QString MarbleWidget::distanceString

(

)

const

Return the current distance string.

Definition at line 1145 of file MarbleWidget.cpp.

void MarbleWidget::enableInput

(

)

[slot]

Definition at line 1178 of file MarbleWidget.cpp.

FileViewModel * MarbleWidget::fileViewModel

(

)

const [slot]

Return a QAbstractItemModel containing files.

Definition at line 1043 of file MarbleWidget.cpp.

QList< MarbleAbstractFloatItem * > MarbleWidget::floatItems

(

)

const

Definition at line 1217 of file MarbleWidget.cpp.

void MarbleWidget::framesPerSecond

(

double

fps

)

[signal]

bool MarbleWidget::geoCoordinates	(	const int	x,
		const int	y,
		double &	lon,
		double &	lat,
		GeoDataPoint::Unit	unit = GeoDataPoint::Degree
	)

Get the earth coordinates corresponding to a pixel in the widget.

Parameters:

	x	the x coordinate of the pixel
	y	the y coordinate of the pixel
	lon	the longitude angle is returned through this parameter
	lat	the latitude angle is returned through this parameter

Returns:

true if the pixel (x, y) is within the globe false if the pixel (x, y) is outside the globe, i.e. in space.

Definition at line 754 of file MarbleWidget.cpp.

bool MarbleWidget::globalQuaternion	(	int	x,
		int	y,
		Quaternion &	q
	)

Get a quaternion representing a point on the earth corresponding to a pixel in the widget.

Parameters:

	x	the x coordinate of the pixel
	y	the y coordinate of the pixel
	q	the out parameter where the result is returned

Returns:

true if the pixel (x, y) is within the globe false if the pixel (x, y) is outside the globe, i.e. in space

Definition at line 771 of file MarbleWidget.cpp.

void MarbleWidget::goHome

(

)

[slot]

Center the view on the default start point with the default zoom.

Definition at line 834 of file MarbleWidget.cpp.

GpxFileModel * MarbleWidget::gpxFileModel

(

)

[slot]

Return a QAbstractItemModel containing GPX files.

Definition at line 1038 of file MarbleWidget.cpp.

void MarbleWidget::home	(	double &	lon,
		double &	lat,
		int &	zoom
	)			[slot]

Get the home point.

Parameters:

	lon	the longitude of the home point.
	lat	the latitude of the home point.
	zoom	the default zoom level of the home point.

Definition at line 635 of file MarbleWidget.cpp.

void MarbleWidget::leaveEvent

(

QEvent *

event

)

[protected]

Reimplementation of the leaveEvent() function in QWidget.

Reimplemented from QWidget.

Definition at line 700 of file MarbleWidget.cpp.

MarbleMap * MarbleWidget::map

(

)

const

Return the map that this view shows.

Definition at line 246 of file MarbleWidget.cpp.

MapQuality MarbleWidget::mapQuality

(

Marble::ViewContext

viewContext = Marble::Still

)

[slot]

Retrieve the map quality depending on the view context.

Definition at line 1099 of file MarbleWidget.cpp.

QPixmap MarbleWidget::mapScreenShot

(

)

Return a QPixmap with the current contents of the widget.

Definition at line 355 of file MarbleWidget.cpp.

GeoSceneDocument * MarbleWidget::mapTheme

(

)

const [slot]

Get the GeoSceneDocument object of the current map theme.

Definition at line 859 of file MarbleWidget.cpp.

QString MarbleWidget::mapThemeId

(

)

const [slot]

Get the ID of the current map theme To ensure that a unique identifier is being used the theme does NOT get represented by its name but the by relative location of the file that specifies the theme:.

Example: mapThemeId = "earth/bluemarble/bluemarble.dgml"

int MarbleWidget::maximumZoom

(

)

const

Return the minimum zoom value for the current map theme.

Definition at line 339 of file MarbleWidget.cpp.

int MarbleWidget::minimumZoom

(

)

const

Return the minimum zoom value for the current map theme.

Definition at line 334 of file MarbleWidget.cpp.

MarbleModel * MarbleWidget::model

(

)

const

Return the model that this view shows.

Definition at line 251 of file MarbleWidget.cpp.

void MarbleWidget::mouseClickGeoPosition	(	double	lon,
		double	lat,
		GeoDataPoint::Unit
	)			[signal]

void MarbleWidget::mouseMoveGeoPosition

(

QString

)

[signal]

void MarbleWidget::moveDown

(

)

[slot]

Move down by the moveStep.

Definition at line 692 of file MarbleWidget.cpp.

void MarbleWidget::moveLeft

(

)

[slot]

Move left by the moveStep.

Definition at line 651 of file MarbleWidget.cpp.

void MarbleWidget::moveRight

(

)

[slot]

Move right by the moveStep.

Definition at line 667 of file MarbleWidget.cpp.

double MarbleWidget::moveStep

(

)

Return how much the map will move if one of the move slots are called.

Returns:

The move step.

Definition at line 324 of file MarbleWidget.cpp.

void MarbleWidget::moveUp

(

)

[slot]

Move up by the moveStep.

Definition at line 684 of file MarbleWidget.cpp.

bool MarbleWidget::needsUpdate

(

)

const

Return if the widget needs to be updated.

Definition at line 303 of file MarbleWidget.cpp.

int MarbleWidget::northPoleY

(

)

Get the Y coordinate of the North Pole.

Returns:

the pixel address of the geographical north pole.

Definition at line 738 of file MarbleWidget.cpp.

int MarbleWidget::northPoleZ

(

)

Get the Z coordinate of the North Pole.

Returns:

the Z coordinate of the geographical north pole.

This function returns the Z coordinate of the north pole. It will return a positive value if the north pole is visible, i.e. pointing towards the viewer. It will return a negative value if the north pole is behind the horizon, i.e. pointing away from the viewer.

Definition at line 743 of file MarbleWidget.cpp.

void MarbleWidget::notifyMouseClick	(	int	x,
		int	y
	)			[slot]

Used to notify about the position of the mouse click.

Definition at line 999 of file MarbleWidget.cpp.

void MarbleWidget::openGpxFile

(

QString &

filename

)

[slot]

Opens a gpx file for viewing on the Marble Widget.

Definition at line 1029 of file MarbleWidget.cpp.

void MarbleWidget::paintEvent

(

QPaintEvent *

event

)

[protected]

Reimplementation of the paintEvent() function in QWidget.

Reimplemented from QWidget.

Definition at line 811 of file MarbleWidget.cpp.

quint64 MarbleWidget::persistentTileCacheLimit

(

)

const

Returns the limit in kilobytes of the persistent (on hard disc) tile cache.

Returns:

the limit of persistent tile cache

QAbstractItemModel * MarbleWidget::placeMarkModel

(

)

const

Returns the model for all the placemarks on the globe.

Definition at line 314 of file MarbleWidget.cpp.

QItemSelectionModel * MarbleWidget::placeMarkSelectionModel

(

)

const

Returns the selection model for all the placemarks on the globe.

Definition at line 319 of file MarbleWidget.cpp.

Quaternion MarbleWidget::planetAxis

(

)

const

Return the quaternion that specifies the rotation of the globe.

Returns:

The quaternion that describes the rotation of the globe.

Definition at line 286 of file MarbleWidget.cpp.

Projection MarbleWidget::projection

(

)

const [slot]

Get the Projection used for the map.

Returns:

Spherical a Globe

Equirectangular a flat map

Mercator another flat map

void MarbleWidget::projectionChanged

(

Projection

)

[signal]

QString MarbleWidget::proxyHost

(

)

const

Definition at line 1207 of file MarbleWidget.cpp.

quint16 MarbleWidget::proxyPort

(

)

const

Definition at line 1212 of file MarbleWidget.cpp.

int MarbleWidget::radius

(

)

const

Return the radius of the globe in pixels.

Definition at line 292 of file MarbleWidget.cpp.

void MarbleWidget::resizeEvent

(

QResizeEvent *

)

[protected]

Reimplementation of the resizeEvent() function in QWidget.

Reimplemented from QWidget.

Definition at line 705 of file MarbleWidget.cpp.

void MarbleWidget::rotateBy

(

const Quaternion &

incRot

)

[slot]

Rotate the view by the angle specified by a Quaternion.

Parameters:

incRot

a quaternion specifying the rotation

Definition at line 504 of file MarbleWidget.cpp.

void MarbleWidget::rotateBy	(	const double &	deltaLon,
		const double &	deltaLat
	)			[slot]

Rotate the view by the two angles phi and theta.

Parameters:

	deltaLon	an angle that specifies the change in terms of longitude
	deltaLat	an angle that specifies the change in terms of latitude

This function rotates the view by two angles, deltaLon ("theta") and deltaLat ("phi"). If we start at (0, 0), the result will be the exact equivalent of (lon, lat), otherwise the resulting angle will be the sum of the previous position and the two offsets.

Definition at line 511 of file MarbleWidget.cpp.

bool MarbleWidget::screenCoordinates	(	const double	lon,
		const double	lat,
		int &	x,
		int &	y
	)

Get the screen coordinates corresponding to geographical coordinates in the widget.

Parameters:

	lon	the lon coordinate of the requested pixel position
	lat	the lat coordinate of the requested pixel position
	x	the x coordinate of the pixel is returned through this parameter
	y	the y coordinate of the pixel is returned through this parameter

Returns:

true if the geographical coordinates are visible on the screen false if the geographical coordinates are not visible on the screen

Definition at line 748 of file MarbleWidget.cpp.

void MarbleWidget::setCenterLatitude

(

double

lat

)

[slot]

Set the latitude for the center point.

Parameters:

lat

the new value for the latitude

Definition at line 601 of file MarbleWidget.cpp.

void MarbleWidget::setCenterLongitude

(

double

lon

)

[slot]

Set the longitude for the center point.

Parameters:

lon

the new value for the longitude

Definition at line 606 of file MarbleWidget.cpp.

void MarbleWidget::setDistance

(

double

distance

)

Set the distance of the observer to the globe in km.

Parameters:

distance

The new distance in km.

Definition at line 1140 of file MarbleWidget.cpp.

void MarbleWidget::setDownloadManager

(

HttpDownloadManager *

downloadManager

)

Set the download manager to load missing tiles.

Parameters:

manager

the manager instance

The instance will be destructed by MarbleWidget when not used any longer.

Definition at line 280 of file MarbleWidget.cpp.

void MarbleWidget::setDownloadUrl

(

const QUrl &

url

)

[slot]

Set the download url to load missing tiles.

Parameters:

url

the url objects

Definition at line 1094 of file MarbleWidget.cpp.

void MarbleWidget::setDownloadUrl

(

const QString &

url

)

[slot]

Set the download url to load missing tiles.

Parameters:

url

the url string

Definition at line 1089 of file MarbleWidget.cpp.