Commit 4b801fd8 authored by Jason Harris's avatar Jason Harris
Browse files

Added API comments to many header files. Also added a debug message

to colorscheme.cpp

svn path=/trunk/kdeedu/kstars/; revision=181286
parent f96f2afc
......@@ -141,9 +141,16 @@ QString ColorScheme::colorNamed( QString name ) const {
QString ColorScheme::colorAt( int i ) const {
SL_it it = KeyName.at(i);
return Palette[ QString(*it) ];
QString color( Palette[ QString(*it) ] );
if ( color.isEmpty() ) {
kdWarning() << i18n( "No color at index %1 found in color scheme." ).arg( i ) << endl;
color = "#FFFFFF"; //set to white if no color found
}
return color;
}
QString ColorScheme::nameAt( int i ) const {
SL_it it = Name.at(i);
return QString(*it);
......
......@@ -23,9 +23,14 @@
class QStringList;
class KConfig;
/**
*@author Jason Harris
*/
/**Implements a color scheme for kstars. Contains a QMap with entries for
*each modifiable color, keyed by the color's ID string. Also contains
*integers that specify the star-color mode (real color, white, red or black)
*and the star color intensity, if real colors are used.
*@short describes a KStars color scheme
*@version 0.9
*@author Jason Harris
*/
class ColorScheme {
......@@ -39,42 +44,91 @@ class ColorScheme {
*/
ColorScheme( const ColorScheme &cs );
/**Destructor
/**Destructor (empty)
*/
~ColorScheme();
/**Return a string describing the RGB color value of the color named 'name'.
*Return white ("#FFFFFF") if no color named 'name' found.
*@param name the ID string of the color to be returned.
*/
QString colorNamed( QString name ) const;
/**Return a string describing the RGB coor value of the color at index
*position i. Return white ("#FFFFFF") if no color at position i found.
*@param i the index of the color in the QMap.
*/
QString colorAt( int i ) const;
/**Return the long name of the color at position i.
*@param i the index of the color in the QMap.
*/
QString nameAt( int i ) const;
/**Return the key ID string of the color at position i.
*@param i the index of the color in the QMap.
*/
QString keyAt( int i ) const;
/**Add a color to the color palette QMap. If a color with the same
*key already exists, it is overwritten.
*@short Add or modify a color in the color scheme
*@param key the key ID for the new color.
*@param color the RGB string for the new color.
*/
void setColor( QString key, QString color );
/**@short Read in a color scheme from a file.
*@param filename the filename from which to read the color scheme.
*/
bool load( QString filename );
/**@short Save the current color scheme to a file whose name is based on
*the 'name' argument.
*@param name The name of the color scheme. The filename is derived from this.
*/
bool save( QString name );
/**@short Copy the color scheme given as an argument.
*@param cs the color scheme to copy.
*/
void copy( const ColorScheme &cs );
/**@short Load the color scheme from the KStars configuration object.
*/
void loadFromConfig( KConfig* );
/**@short Save the current color scheme to the KStars configuration object.
*/
void saveToConfig( KConfig* );
/**@returns the number of colors in the color scheme.
*/
#if (QT_VERSION < 300)
unsigned int numberOfColors() const { return (int)Palette.count(); }
#else
unsigned int numberOfColors() const { return (int)Palette.size(); }
#endif
/**@returns the star color mode. { 0 = real colors; 1 = solid red;
*2 = solid black; 3 = solid white }
*/
int starColorMode() const { return StarColorMode; }
/**@returns the star color intensity parameter. The higher the value,
*the more saturated the star colors will appear. This only has meaning
*when StarColorMode = 0 {real colors}.
*/
int starColorIntensity() const { return StarColorIntensity; }
/**@short Set the star color mode.
*@param mode the new star color mode value.
*/
void setStarColorMode( int mode ) { StarColorMode = mode; }
/**@short Set the star color intensity.
*@param intens the new star color intensity value.
*/
void setStarColorIntensity( int intens) { StarColorIntensity = intens; }
private:
......
......@@ -30,26 +30,35 @@ class QHBoxLayout;
class QVBoxLayout;
/**DetailDialog is a window showing detailed information for a selected object.
*Also shows a piece of the skymap centered on the object.
*The kind of information displayed depends upon the object type:
*
*Stars: Long name, Genetive name, Spectral Type, Magnitude,
*@author Jason Harris
*Currently, the DetailDialog shows information regarding the object's names,
*type, magnitude, coordinates and rise/transit/set events.
*@short Show a dialog with detailed information about an object.
*@author Jason Harris
*@version 0.9
*/
class DetailDialog : public KDialogBase {
Q_OBJECT
public:
/**Constructor.*/
DetailDialog(SkyObject *o, QDateTime lt, GeoLocation *geo, QWidget *parent=0, const char *name=0);
/**Destructor (empty)*/
~DetailDialog() {}
private:
/**NameBox is an internal class that encapsulates the object's name, type,
*and magnitude information.
*/
class NameBox : public QGroupBox {
public:
/**Constructor for stars */
/**Constructor*/
NameBox( QString pname, QString oname, QString typelabel, QString type,
QString mag, QWidget *parent, const char *name=0 );
/**Destructor (empty)*/
~NameBox() {}
private:
QLabel *PrimaryName, *OtherNames, *TypeLabel, *Type, *MagLabel, *Mag;
QLabel *SizeLabel, *Size;
......@@ -58,10 +67,16 @@ private:
QGridLayout *glay;
};
/**CoordBox is an internbal class that encapsulates the object's coordinate data.
*/
class CoordBox : public QGroupBox {
public:
/**Constructor*/
CoordBox( SkyObject *o, QDateTime lt, QWidget *parent, const char *name=0 );
/**Destructor (empty)*/
~CoordBox() {}
private:
QLabel *RALabel, *DecLabel, *RA, *Dec;
QLabel *AzLabel, *AltLabel, *Az, *Alt;
......@@ -70,9 +85,15 @@ private:
QGridLayout *glayCoords;
};
/**RiseSetBox is an internal class that encapsulates data regarding the object's
*rise/transit/set events.
*/
class RiseSetBox : public QGroupBox {
public:
/**Constructor*/
RiseSetBox( SkyObject *o, QDateTime lt, GeoLocation *geo, QWidget *parent, const char *name=0 );
/**Destructor (empty)*/
~RiseSetBox() {}
private:
QLabel *RTime, *TTime, *STime;
......
......@@ -26,9 +26,13 @@
#include <qstring.h>
/**InfoBox encapsulates a lightweight "window" to be drawn directly on a pixmap.
*This preliminary version contains a text string, and geometry (x,y,w,h).
*@author Jason Harris
*/
*The box contains up to three strings of information, drawn one per line.
*The box is automatically resized to fit the longest line. It can be moved and
*"shaded"; in its shaded state, only the first string is visible.
*@short An interactive box containing three lines of text drawn directly on a qpixmap.
*@author Jason Harris
*@version 0.9
*/
class InfoBox : public QObject {
Q_OBJECT
......@@ -37,73 +41,141 @@ public:
*and default geometry
*/
InfoBox();
/**general constructor. Specify The text string, x,y position and size.
/**general constructor. Specify the text string, x,y position, and shaded state.
*@param x The initial x-position
*@param y The initial y-position
*@param shade The initial Shade state
*@param t1 The first line of text
*@param t2 The second line of text
*@param t3 The third line of text
*/
InfoBox( int x, int y, bool shade, QString t1="", QString t2="", QString t3="" );
/**general constructor. Specify the text string, x,y position, and shaded state.
*Differs from the above function only in the data types of its arguments.
*@param p The initial position
*@param shade The initial Shade state
*@param t1 The first line of text
*@param t2 The second line of text
*@param t3 The third line of text
*/
InfoBox( QPoint p, bool shade, QString t1="", QString t2="", QString t3="" );
/**Destructor (empty)*/
~InfoBox();
/**Draw the InfoBox on the specified QPainter*/
/**Draw the InfoBox on the specified QPainter
*@param p The QPainter on which to draw the box
*@param BGColor The background color, if it is to be drawn
*@param fillBG If true, then fill in the box background. Otherwise, leave it transparent.
*/
void draw( QPainter &p, QColor BGColor, bool fillBG );
/**Toggle between the shaded and normal states. Also update the box size and
*emit the "shaded" signal.
*/
bool toggleShade();
/**Reset the x,y position. Check the anchors*/
/**Reset the x,y position. Check to see if box should be "anchored"
*to a screen edge.
*@param x The new x-position
*@param y The new y-position
*/
void move( int x, int y );
/**Reset the x,y position. Check to see if box should be "anchored"
*to a screen edge. Differs from the above function only in the types
*of its arguments.
*@param p The new position
*/
void move( QPoint p );
/**Reset the width and height*/
/**Reset the width and height
*@param w The new width
*@param h The new height
*/
void resize( int w, int h ) { Size.setWidth( w ); Size.setHeight( h ); }
/**Reset the width and height using a QSize argument*/
/**Reset the width and height using a QSize argument
*@param s The new size
*/
void resize( QSize s ) { Size.setWidth( s.width() ); Size.setHeight( s.height() ); }
/**Set the size of the box to fit the current displayed text */
void updateSize();
/**Make sure the InfoBox is inside (or outside) the QRect r.
/**Make sure the InfoBox is inside (or outside) the QRect r. Move it if necessary.
*@returns true if the function was able to obey the constraint; otherwise returns false.
*@param r The QRect that the infobox must be made to be inside (or outside).
*@param inside If true, then the infobox must be inside r; otherwise, it must be outside r.
*/
bool constrain( QRect r, bool inside=true );
/**Reset the text string*/
/**Reset the first text string
*@param newt The new text string
*/
void setText1( QString newt ) { Text1 = newt; }
/**Reset the second text string
*@param newt The new text string
*/
void setText2( QString newt ) { Text2 = newt; }
/**Reset the third text string
*@param newt The new text string
*/
void setText3( QString newt ) { Text3 = newt; }
//temporarily, padx() and pady() simply return a constant
//for now, padx() and pady() simply return a constant
/**@returns the padding between the text and the box edge in the x-direction.*/
int padx() const { return 6; }
/**@returns the padding between the text and the box edge in the y-direction.*/
int pady() const { return 6; }
/**set the isHidden flag according to the bool argument */
void setVisible( bool t ) { Visible = t; }
/**Accessors for private data*/
//Accessors for private data
/**@returns The x-position of the infobox*/
int x() const { return Pos.x(); }
/**@returns The y-position of the infobox*/
int y() const { return Pos.y(); }
/**@returns The position of the infobox*/
QPoint pos() const { return Pos; }
/**@returns The width of the infobox*/
int width() const { return Size.width(); }
/**@returns The height of the infobox*/
int height() const { return Size.height(); }
/**@returns The size of the infobox*/
QSize size() const { return Size; }
/**@returns the position and size of the infobox*/
QRect rect() const;
/**@returns true if infobox is currently visible (i.e., not hidden)*/
bool isVisible() const { return Visible; }
/**@returns The first string of the infobox*/
QString text1() const { return Text1; }
/**@returns The second string of the infobox*/
QString text2() const { return Text2; }
/**@returns The third string of the infobox*/
QString text3() const { return Text3; }
QRect rect() const;
/**@returns true if infobox is currently anchored to right edge of the QPixmap*/
bool anchorRight() const { return AnchorRight; }
/**@returns true if infobox is currently anchored to bottom edge of the QPixmap*/
bool anchorBottom() const { return AnchorBottom; }
/**Set AnchorRight according to bool argument*/
void setAnchorRight( const bool ar ) { AnchorRight = ar; }
/**Set AnchorBottom according to bool argument*/
void setAnchorBottom( const bool ab ) { AnchorBottom = ab; }
signals:
/**Emit signal that Infobox was moved*/
void moved( QPoint p );
/**Emit signal that infobox shade-state was changed*/
void shaded( bool s );
private:
bool Shaded, Visible, AnchorRight, AnchorBottom;
//TextWidth, TextHeight are the text dimensions when box is unshaded;
//TextWidth1, TextHeight1 are the text dimensions when the box is shaded.
int FullTextWidth, FullTextHeight;
int ShadedTextWidth, ShadedTextHeight;
QPoint Pos;
......
......@@ -29,13 +29,34 @@
#include "skypoint.h"
#include "infobox.h"
/**
*@author Jason Harris
/**Infoboxes manages the three infobox objects which are drawn on the Skymap.
*Each Infobox is a member variable in Infoboxes. Infoboxes handles user
*interactions with the boxes, and makes sure they do not overlap each other or
*move outside the bounds of the SkyMap.
*@short Infoboxes encapsulates and manages the three Infobox objects
*@author Jason Harris
*@version 0.9
*/
class InfoBoxes : public QObject {
Q_OBJECT
public:
/**Constructor. Create three infoboxes and place them in the skymap.
*@param w The width of the region in which the boxes can be drawn
*(typically the width of the SkyMap)
*@param h The height of the region in which the boxes can be drawn
*(typically the height of the SkyMap)
*@param tx the x-position of the Time infobox
*@param ty the y-position of the Time infobox
*@param gx the x-position of the Geographic infobox
*@param gy the y-position of the Geographic infobox
*@param fx the x-position of the Focus-object infobox
*@param fy the y-position of the Focus-object infobox
*@param colorText The foreground color for infoboxes
*@param colorGrab The foreground color for infoboxes, while they are
*"grabbed" by the user
*@param colorText The background color for infoboxes
*/
InfoBoxes( int w, int h,
int tx=0, int ty=0, bool tshade=false,
int gx=0, int gy=600, bool gshade=false,
......@@ -44,6 +65,20 @@ public:
QColor colorGrab=QColor("red"),
QColor colorBG=QColor("black") );
/**Constructor. Create three infoboxes and place them in the skymap.
*Differs from the above function only in the types of its arguments.
*@param w The width of the region in which the boxes can be drawn
*(typically the width of the SkyMap)
*@param h The height of the region in which the boxes can be drawn
*(typically the height of the SkyMap)
*@param tp the position of the Time infobox
*@param gp the position of the Geographic infobox
*@param fp the position of the Focus-object infobox
*@param colorText The foreground color for infoboxes
*@param colorGrab The foreground color for infoboxes, while they are
*"grabbed" by the user
*@param colorText The background color for infoboxes
*/
InfoBoxes( int w, int h,
QPoint tp, bool tshade,
QPoint gp, bool gshade,
......@@ -52,57 +87,138 @@ public:
QColor colorGrab=QColor("red"),
QColor colorBG=QColor("black") );
/**Destructor (empty)*/
~InfoBoxes();
/**@returns pointer to the Time infobox*/
InfoBox *timeBox() { return TimeBox; }
/**@returns pointer to the Geographic infobox*/
InfoBox *geoBox() { return GeoBox; }
/**@returns pointer to the Focus-object infobox*/
InfoBox *focusBox() { return FocusBox; }
/**Resets the width and height parameters. These usually reflect the size
*of the Skymap widget (Skymap::resizeEvent() calls this function).
*Will also reposition the infoboxes to fit the new size. Infoboxes
*that were along an edge will remain along thr edge.
*/
/**Resets the width and height parameters. These usually reflect the size
*of the Skymap widget (Skymap::resizeEvent() calls this function).
*Will also reposition the infoboxes to fit the new size. Infoboxes
*that were along an edge will remain along the edge.
*@param w The new width
*@param h The new height
*/
void resize( int w, int h );
/**@returns the width of the region containing the infoboxes (usually the
*width of the Skymap)
*/
/**@returns the width of the region containing the infoboxes (usually the
*width of the Skymap)
*/
int width() const { return Width; }
/**@returns the height of the region containing the infoboxes (usually the
*height of the Skymap)
*/
/**@returns the height of the region containing the infoboxes (usually the
*height of the Skymap)
*/
int height() const { return Height; }
/**Draw the boxes on a Qpainter object (representing the SkyMap).
*@param p The QPainter on which to draw the boxes.
*@param FGColor The foreground color (Pen color) to use when drawing boxes.
*@param grabColor The foreground color to use if the box is "grabbed" by the user.
*@param BGColor The background color (brush color) to use, if fillBG is true
*@param fillBG If true, the boxes will be filled with BGColor; otherwise, they will be transparent.
*/
void drawBoxes( QPainter &p, QColor FGColor=QColor("white"),
QColor grabColor=QColor("red"), QColor BGColor=QColor("black"),
bool fillBG=false );
/**Determine whether a mouse click occurred inside one of the infoboxes.
*Also, set the internal variable GrabBox to indicate which box was grabbed.
*Finally, set the internal variable GrabPos to record the relative position of the
*mouse cursor inside the box (we hold this position constant while dragging).
*@param e The mouse event to check (it's a mousePressEvent)
*@returns true if the mouse press occurred inside one of the infoboxes.
*/
bool grabBox( QMouseEvent *e );
/**Set the internal variable GrabBox to 0, indicating that no box is currently
*grabbed. Also determine if any box should be anchored to an edge. (This
*is called by SkyMap::mouseReleaseEvent() )
*@returns true if a box was grabbed in the first place; otherwise, return false.
*/
bool unGrabBox();
/**Move the Grabbed box around by keeping the relative position of the mouse cursor
*to the box position equal to GrabPos. (this is called by SkyMap::mouseMoveEvent() ).
*Once the box has been moved, we call fixCollisions() to make sure the boxes don't
*overlap or exceed the SkyMap boundaries.
*@param e The mouse event which contains the new mouse cursor position
*@returns false if no box is grabbed; otherwise, moves the grabbed box and returns true.
*/
bool dragBox( QMouseEvent *e );
/**Toggle the shade-state of the infobox in which the user double-clicked.
*After shading the box, call fixCollisions() on the other two boxes.
*(This is called by SkyMap::mouseDoubleClickEvent() )
*@param e the mouse event containing the position of the double-click.
*@returns false if the double-click was not inside any box; otherwise shade the
*target box and return true.
*/
bool shadeBox( QMouseEvent *e );
/**Make sure the target Infobox lies within the SkyMap boundaries, and that it does
*not overlap with the other two Infoboxes. If an overlap is detected, the target
*box does a test-displacement each direction until there is no overlap (or the
*SkyMap boundary is reached). The target box is then moved in the direction that
*required the smallest displacement to remove the overlap.
*@param target the infobox which should be tested for collisions.
*@returns false if the box collisions could not be resolved; otherwise, returns true.
*/
bool fixCollisions( InfoBox *target );
/**@returns true if the collection of infoboxes is visible (i.e., not hidden).
*/
bool isVisible() { return Visible; }
public slots:
/**Set whether the Infoboxes should be drawn, according to the bool argument.
*This is the visibility setting for all three boxes. Each individual box
*also has its own Visible parameter. A box is only drawn if both
*Infoboxes::Visible /and/ Infobox::Visible are true.
*@param t If true, the Infoboxes will be drawn.
*/
void setVisible( bool t ) { Visible = t; }
/**Call the TimeBox's setVisible() function.
*@param t The bool parameter to send
*/
void showTimeBox( bool t ) { TimeBox->setVisible( t ); }
/**Call the GeoBox's setVisible() function.
*@param t The bool parameter to send
*/
void showGeoBox( bool t ) { GeoBox->setVisible( t ); }
/**Call the FocusBox's setVisible() function.
*@param t The bool parameter to send
*/
void showFocusBox( bool t ) { FocusBox->setVisible( t ); }
/**Update the Time-related labels according to the arguments.
/**Update the TimeBox strings according to the arguments.
*The arguments are date/time objects; this function converts them to
*strings and displays them in the TimeBox.
*@param ut The Universal Time date/time object
*@param lt The Local Time date/time object
*@param lst The Sidereal Time object
*@param jd The Julian Date (long double)
*/
void timeChanged(QDateTime ut, QDateTime lt, QTime lst, long double julian);
/**Update the Location-related labels.
/**Update the GeoBox strings according to the argument.
*@param geo The Geographic Location (we get the name, longitude and latitude from this)
*/
void geoChanged(const GeoLocation *geo);
/**Update the focus coordinate-related labels.
/**Update the FocusBox coordinates strings according to the argument.
*@param p the SkyPoint object from which we get the coordinates.
*/
void focusCoordChanged(const SkyPoint *p);
/**Update the focus object-related labels.
/**Update the FocusBox name string according to the argument.
*@param n The object name
*/
void focusObjChanged(const QString &n);
......
......@@ -28,12 +28,17 @@
/**
*A subclass of SkyObject that provides additional information
*needed for solar system objects. KSPlanet may be used
*directly for all planets except Pluto. The Sun are subclassed from
*directly for all planets except Pluto. The Sun is subclassed from
*KSPlanet.
*
*KSPlanet contains subclasses to manage the computations of a planet's position.
*The position is computed as a series of sinusoidal sums, similar to a Fourier
*transform. See "Astronomical Algorithms" by Jean Meeus or the file README.planetmath
*for details.
*@short Provides necessary information about objects in the solar system.
*@author Jason Harris
*@version 0.9
*/
*@author Jason Harris
*@version 0.9
*/
class KSPlanet : public KSPlanetBase {
public:
......@@ -68,12 +73,20 @@ public:
/**Calculate the ecliptic longitude and latitude of the planet for
*the given date (expressed in Julian Millenia since J2000). A reference
*to the ecliptic coordinates is returned as the second object.
*@param jm Julian Millenia (=jd/1000)
*@param ret The ecliptic coordinates are returned by reference through this argument.
*/
virtual void calcEcliptic(double jm, EclipticPosition &ret) const;
protected:
bool data_loaded;
/**OrbitData contains doubles A,B,C which represent a single term in a planet's
*positional expansion sums (each sum-term is A*COS(B+C*T)).
*@author Mark Hollomon
*@version 0.9
*/
class OrbitData {
public:
double A, B, C;
......@@ -82,6 +95,14 @@ protected:
};
typedef QVector<OrbitData> OBArray[6];
/**OrbitDataColl contains three groups of six QVectors. Each QVector is a
*list of OrbitData objects, representing a single sum used in computing