[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-commits
Subject: [marble/esasocis-2012-eclipse] src/plugins/render/eclipses: EclipsesPlugin: Document methods
From: Rene Kuettner <rene () bitkanal ! net>
Date: 2013-01-19 11:24:01
Message-ID: 20130119112401.A5A68A6091 () git ! kde ! org
[Download RAW message or body]
Git commit 0cb76a73ca65dc41ec4128e80a13b8da1d583286 by Rene Kuettner.
Committed on 19/01/2013 at 12:16.
Pushed by renek into branch 'esasocis-2012-eclipse'.
EclipsesPlugin: Document methods
M +152 -2 src/plugins/render/eclipses/EclipsesItem.h
M +46 -1 src/plugins/render/eclipses/EclipsesListDialog.h
M +2 -4 src/plugins/render/eclipses/EclipsesModel.cpp
M +98 -4 src/plugins/render/eclipses/EclipsesModel.h
M +9 -5 src/plugins/render/eclipses/EclipsesPlugin.cpp
M +46 -1 src/plugins/render/eclipses/EclipsesPlugin.h
http://commits.kde.org/marble/0cb76a73ca65dc41ec4128e80a13b8da1d583286
diff --git a/src/plugins/render/eclipses/EclipsesItem.h \
b/src/plugins/render/eclipses/EclipsesItem.h index d3fe86b..1522480 100644
--- a/src/plugins/render/eclipses/EclipsesItem.h
+++ b/src/plugins/render/eclipses/EclipsesItem.h
@@ -23,11 +23,25 @@
namespace Marble
{
+/**
+ * @brief The representation of an eclipse event
+ *
+ * This class represents an eclipse event on earth. It calculates all
+ * basic information like date and visibility upon initialization.
+ * Expensive calculations like boundary polygons are done the first time
+ * they are requested.
+ *
+ * The calculations are done using the eclsolar backend that has to be
+ * passed to the constructor.
+ */
class EclipsesItem : public QObject
{
Q_OBJECT
public:
+ /**
+ * @brief A type of an eclipse event
+ */
enum EclipsePhase {
PartialSun = 1,
NonCentralAnnularSun = 2,
@@ -37,43 +51,179 @@ public:
AnnularTotalSun = 6
};
+ /**
+ * @brief Construct the EclipseItem object and trigger basic calculations
+ * @param ecl The EclSolar backend
+ * @param parent The parent object
+ */
EclipsesItem( EclSolar *ecl, int index, QObject *parent = 0 );
~EclipsesItem();
+ /**
+ * @brief The index of the eclipse event
+ *
+ * Returns the index of the eclipse event.
+ *
+ * @return The eclipse events index.
+ */
int index() const;
+ /**
+ * @brief Check if the event takes place at a given datetime
+ * @param dateTime The date time to check
+ *
+ * Checks wheter or not this eclipse event takes place at the given
+ * @p dateTime. This is true if @p dateTime is between the global
+ * start and end dates of the event.
+ *
+ * @return True if the event takes place at @p dateTime or false otherwise.
+ */
bool takesPlaceAt( const QDateTime &dateTime ) const;
- QDateTime dateTime() const;
-
+ /**
+ * @brief Returns the phase of this eclipse event
+ * @return the phase or type of this eclipse event
+ * @see phaseText
+ */
EclipsesItem::EclipsePhase phase() const;
+
+ /**
+ * @brief Returns a human readable representation of the eclipse type
+ * @return A string representing the eclipse's type
+ * @see phase
+ */
QString phaseText() const;
+ /**
+ * @brief Returns the date of the eclipse event's maximum
+ * @return The DateTime of the eclipse's maximum
+ * @see maxLocation
+ */
const QDateTime& dateMaximum() const;
+
+ /**
+ * @brief Returns the start date of the eclipse's partial phase
+ * @return The start date of the partial phase
+ * @see endDatePartial
+ */
const QDateTime& startDatePartial() const;
+
+ /**
+ * @brief Returns the end date of the eclipse's partial phase
+ * @return The end date of the partial phase
+ * @see startDatePartial
+ */
const QDateTime& endDatePartial() const;
+
+ /**
+ * @brief Returns the number of hours the partial phase takes place
+ * @return The number of hours of the partial phase
+ * @see startDatePartial, endDatePartial
+ */
int partialDurationHours() const;
+
+ /**
+ * @brief Returns the start date of the eclipse's total phase
+ *
+ * If the eclipse has a total phase, the date and time of its beginning
+ * is returned. If this is no total eclipse, an invalid datetime object
+ * will be returned.
+ *
+ * @return The start date of the total phase or an invalid date
+ * @see endDateTotal
+ */
const QDateTime& startDateTotal() const;
+
+ /**
+ * @brief Returns the end date of the eclipse's total phase
+ *
+ * If the eclipse has a total phase, the date and time of its ending
+ * is returned. If this is no total eclipse, an invalid datetime object
+ * will be returned.
+ *
+ * @return The end date of the total phase or an invalid date
+ * @see startDateTotal
+ */
const QDateTime& endDateTotal() const;
+ /**
+ * @brief Return the eclipse's magnitude
+ * @return The magnitude of the eclipse
+ */
double magnitude() const;
+ /**
+ * @brief Return the coordinates of the eclipse's maximum
+ * @return GeoDataCoordinates of the eclipse's maximum
+ * @see dateMaximum
+ */
const GeoDataCoordinates& maxLocation();
+ /**
+ * @brief The eclipse's central line
+ * @return The central line of the eclipse
+ */
const GeoDataLineString& centralLine();
+ /**
+ * @brief Return the eclipse's umbra
+ * @return The eclipse's umbra
+ */
const GeoDataLinearRing& umbra();
+
+ /**
+ * @brief Return the eclipse's southern penumbra
+ * @return The eclipse's southern penumbra
+ */
const GeoDataLineString& southernPenUmbra();
+
+ /**
+ * @brief Return the eclipse's northern penumbra
+ * @return The eclipse's northern umbra
+ */
const GeoDataLineString& northernPenUmbra();
+ /**
+ * @brief Return the eclipse's sun boundaries
+ * @return The eclipse's sun boundaries
+ */
const QList<GeoDataLinearRing>& sunBoundaries();
+ /**
+ * @brief Return the shadow cone of the umbra
+ * @return The shadow cone of the umbra
+ */
const QList<GeoDataCoordinates>& shadowConeUmbra();
+
+ /**
+ * @brief Return the shadow cone of the penumbra
+ * @return The shadow cone of the penumbra
+ */
const QList<GeoDataCoordinates>& shadowConePenUmbra();
+
+ /**
+ * @brief Return the shadow cone of the penumbra at 60 percent magnitude
+ * @return The shadow cone of the penumbra at 60 percent magnitude
+ */
const QList<GeoDataCoordinates>& shadowCone60MagPenUmbra();
private:
+ /**
+ * @brief Initialize the eclipse item
+ *
+ * Initializes all properties of the eclipse item and does basic
+ * calculations. Expensive calculations are done as required.
+ *
+ * @see calculate
+ */
void initialize();
+
+ /**
+ * @brief Do detailed calculations
+ *
+ * Do the expensive calculations (like shadow cones) for this eclipse
+ * event. This is normally called on the first request of such data.
+ */
void calculate();
EclSolar *m_ecl;
diff --git a/src/plugins/render/eclipses/EclipsesListDialog.h \
b/src/plugins/render/eclipses/EclipsesListDialog.h index 8a57f39..fdb3285 100644
--- a/src/plugins/render/eclipses/EclipsesListDialog.h
+++ b/src/plugins/render/eclipses/EclipsesListDialog.h
@@ -25,6 +25,11 @@ namespace Marble {
class EclipsesModel;
class MarbleModel;
+/**
+ * @brief The eclipse browser dialog
+ *
+ * This implements the logic for the eclipse browser dialog.
+ */
class EclipsesListDialog : public QDialog
{
Q_OBJECT
@@ -34,18 +39,58 @@ public:
QWidget *parent = 0 );
~EclipsesListDialog();
+ /**
+ * @brief Set the year
+ *
+ * This sets the year the browser currently shows eclipses for.
+ *
+ * @see year
+ */
void setYear( int year );
+
+ /**
+ * @brief Return the year the browser is set to
+ *
+ * @return The year the browser shows eclipses for at the moment
+ * @see setYear
+ */
int year() const;
Q_SIGNALS:
+ /**
+ * @brief This signal is emitted when the use clicks the "show" button
+ * @param year the year of the selected eclipse event
+ * @param index the index of the selected eclipse item
+ */
void buttonShowClicked( int year, int index );
protected Q_SLOTS:
+ /**
+ * @brief Accept the dialog
+ *
+ * This emits the buttonShowClicked signal
+ *
+ * @see buttonShowClicked
+ */
void accept();
+
+ /**
+ * @brief Update the list of eclipses for the given year
+ * @param year The year to list eclipses for
+ */
void updateEclipsesListForYear( int year );
- void updateButtonsState();
+
+ /**
+ * @brief Update the dialog's button states
+ *
+ * Disable/enable the show button according to the current selection.
+ */
+ void updateButtonState();
protected:
+ /**
+ * @brief Intialize the object
+ */
void initialize();
private:
diff --git a/src/plugins/render/eclipses/EclipsesModel.cpp \
b/src/plugins/render/eclipses/EclipsesModel.cpp index 08cf350..65b6eda 100644
--- a/src/plugins/render/eclipses/EclipsesModel.cpp
+++ b/src/plugins/render/eclipses/EclipsesModel.cpp
@@ -73,17 +73,15 @@ int EclipsesModel::year() const
return m_currentYear;
}
-EclipsesItem* EclipsesModel::eclipseWithIndex( int year, int index )
+EclipsesItem* EclipsesModel::eclipseWithIndex( int index )
{
- setYear( year );
-
foreach( EclipsesItem *item, m_items ) {
if( item->index() == index ) {
return item;
}
}
- return 0;
+ return NULL;
}
QList<EclipsesItem*> EclipsesModel::items() const
diff --git a/src/plugins/render/eclipses/EclipsesModel.h \
b/src/plugins/render/eclipses/EclipsesModel.h index dc493da..4bb961a 100644
--- a/src/plugins/render/eclipses/EclipsesModel.h
+++ b/src/plugins/render/eclipses/EclipsesModel.h
@@ -27,24 +27,92 @@ class EclipsesItem;
class GeoPainter;
class GeoDataCoordinates;
+/**
+ * @brief The model for eclipses
+ *
+ * EclipsesModel provides an interface to the eclsolar backend. Instances
+ * of this class hold EclipseItem objects for every eclipse event of a given
+ * year. Furthermore, it implements QTs AbstractItemModel interface and can
+ * be used with QTs view classes.
+ */
class EclipsesModel : public QAbstractItemModel
{
Q_OBJECT
+
public:
EclipsesModel( const MarbleModel *model, QObject *parent = 0 );
~EclipsesModel();
+ /**
+ * @brief Return the current observation point
+ *
+ * Returns the current observation point on which location specific
+ * eclipse calculations are based.
+ *
+ * @return GeoDataCoordinates of the current observation point
+ * @see setObservationPoint
+ */
const GeoDataCoordinates& observationPoint() const;
+
+ /**
+ * @brief Set the current observation point
+ *
+ * @param coords
+ *
+ * Set the current observation point to @p coords. This will mark all
+ * items for recalculation of eclipses details according to the new
+ * observation point.
+ *
+ * @see observationPoint
+ */
void setObservationPoint( const GeoDataCoordinates &coords );
+ /**
+ * @brief Set the year
+ *
+ * @param year The year
+ *
+ * Sets the year to @p year. This clears all items in the model and
+ * fills it with all eclipse items for the given year.
+ *
+ * @see year
+ */
void setYear( int year );
- int year() const;
- EclipsesItem* eclipseWithIndex( int year, int index );
+ /**
+ * @brief Return the year
+ *
+ * Returns the year of all eclipse items in this model.
+ *
+ * @return the year of eclipse items in this model
+ * @see setYear
+ */
+ int year() const;
+ /**
+ * @brief Get eclipse item of a given year
+ *
+ * @param index
+ *
+ * This returns the eclipse item with @p index for the year set. If
+ * there is no eclipse with @p index in the set year, NULL will be
+ * returned.
+ *
+ * @return the requested eclipse item or NULL if there is no eclipse
+ * @see setYear
+ */
+ EclipsesItem* eclipseWithIndex( int index );
+
+ /**
+ * @brief Return the items in this model
+ *
+ * Returns a list of items currently in the model.
+ *
+ * @return list of items in the model
+ */
QList<EclipsesItem*> items() const;
- // QT model interface
+ // QT abstract item model interface
QModelIndex index( int row, int column,
const QModelIndex &parent = QModelIndex() ) const;
QModelIndex parent( const QModelIndex &index ) const;
@@ -56,9 +124,35 @@ public:
int role = Qt::DisplayRole ) const;
private:
- void paintItem( EclipsesItem *item, GeoPainter *painter );
+ /**
+ * @brief Add an item to the model
+ * @param item the item to add
+ *
+ * Adds @p item to the model.
+ *
+ * @see clear
+ */
void addItem( EclipsesItem *item );
+
+ /**
+ * @brief Clears all items
+ *
+ * Clear the model by removing all items.
+ *
+ * @see addItem
+ */
void clear();
+
+ /**
+ * @brief Update the list of eclipse items
+ *
+ * This forces an update of the current list of eclipse items by
+ * calculating all eclipse events for the currently set year and
+ * adding them to the model. All previously added items are
+ * cleared before.
+ *
+ * @see clear
+ */
void update();
const MarbleModel *m_marbleModel;
diff --git a/src/plugins/render/eclipses/EclipsesPlugin.cpp \
b/src/plugins/render/eclipses/EclipsesPlugin.cpp index 50a7d7d..6830d52 100644
--- a/src/plugins/render/eclipses/EclipsesPlugin.cpp
+++ b/src/plugins/render/eclipses/EclipsesPlugin.cpp
@@ -207,7 +207,7 @@ void EclipsesPlugin::initialize()
readSettings();
updateEclipses();
- updateMenuItems();
+ updateMenuItemState();
updateSettings();
}
@@ -222,7 +222,7 @@ bool EclipsesPlugin::eventFilter( QObject *object, QEvent *e )
MarbleWidget *widget = dynamic_cast<MarbleWidget*> (object);
if ( widget && m_marbleWidget != widget ) {
connect( widget, SIGNAL(themeChanged(QString)),
- this, SLOT(updateMenuItems()) );
+ this, SLOT(updateMenuItemState()) );
m_marbleWidget = widget;
m_clock = m_marbleWidget->model()->clock();
connect( m_clock, SIGNAL(timeChanged()),
@@ -447,7 +447,7 @@ void EclipsesPlugin::updateEclipses()
}
}
-void EclipsesPlugin::updateMenuItems()
+void EclipsesPlugin::updateMenuItemState()
{
if( !isInitialized() ) {
return;
@@ -464,7 +464,11 @@ void EclipsesPlugin::updateMenuItems()
void EclipsesPlugin::showEclipse( int year, int index )
{
- EclipsesItem *item = m_model->eclipseWithIndex( year, index );
+ if( m_model->year() != year ) {
+ m_model->setYear( year );
+ }
+
+ EclipsesItem *item = m_model->eclipseWithIndex( index );
Q_ASSERT( item );
if( item ) {
@@ -486,7 +490,7 @@ void EclipsesPlugin::showEclipseFromMenu( QAction *action )
showEclipse( date.year(), index );
}
-}
+} // namespace Marble
Q_EXPORT_PLUGIN2( EclipsesPlugin, Marble::EclipsesPlugin )
diff --git a/src/plugins/render/eclipses/EclipsesPlugin.h \
b/src/plugins/render/eclipses/EclipsesPlugin.h index 350eeb2..7b16617 100644
--- a/src/plugins/render/eclipses/EclipsesPlugin.h
+++ b/src/plugins/render/eclipses/EclipsesPlugin.h
@@ -35,6 +35,8 @@ class EclipsesListDialog;
/**
* @brief This plugin displays solar eclipses.
*
+ * It utilizes Gerhard Holtcamps eclsolar class to render nice
+ * visualizations of eclipse events on earth.
*/
class EclipsesPlugin : public RenderPlugin,
public DialogConfigurationInterface
@@ -49,6 +51,9 @@ public:
explicit EclipsesPlugin( const MarbleModel *marbleModel );
virtual ~EclipsesPlugin();
+ // this is the implementation of the RenderPlugin interface
+ // see RenderPlugin.h for a description
+
QStringList backendTypes() const;
QString renderPolicy() const;
QStringList renderPosition() const;
@@ -83,12 +88,52 @@ private Q_SLOTS:
void readSettings();
void writeSettings();
void updateSettings();
+
+ /**
+ * @brief Update list of eclipses for the current year
+ *
+ * This calculates the list of eclipses for the year the marble clock
+ * is set to.
+ */
void updateEclipses();
- void updateMenuItems();
+ /**
+ * @brief Show an eclipse event on the marble map
+ *
+ * @param year The year the eclipse event happens
+ * @param index The index of the eclipse in this year
+ *
+ * Shows the eclipse with index @p index in year @p year by setting
+ * the marble clock to the time of the eclipse's maximum.
+ */
void showEclipse( int year, int index );
+
+ /**
+ * @brief Show an eclipse event selected from the menu
+ *
+ * @param action The menu items action
+ *
+ * Shows the eclipse the menu item given by @p action refers to.
+ * The eclipse's index is stored in the actions data field while the
+ * year is taken from the action's text.
+ */
void showEclipseFromMenu( QAction *action );
+ /**
+ * @brief Update menu item state
+ *
+ * Updates the state of the plugin's menu items. They will be disabled for
+ * non earth themes since we only support eclipse events on earth.
+ */
+ void updateMenuItemState();
+
+ /**
+ * @brief List eclipses in the eclipses browser for a given year
+ *
+ * @param year The year to calculate eclipse events for
+ */
+ void updateListDialogForYear( int year );
+
private:
bool m_isInitialized;
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic