Kstars

skycomponent.h
1 /*
2  SPDX-FileCopyrightText: 2005 Thomas Kabelmann <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "skypoint.h"
10 #include "typedef.h"
11 
12 class QString;
13 
14 class SkyObject;
15 class SkyPoint;
16 class SkyComposite;
17 class SkyPainter;
18 
19 /**
20  * @class SkyComponent
21  * SkyComponent represents an object on the sky map. This may be a star, a planet or an imaginary
22  * line like the equator.
23  * The SkyComponent uses the composite design pattern. So if a new object type is needed, it has to
24  * be derived from this class and must be added into the hierarchy of components.
25  *
26  * \section Overview Overview
27  * KStars utilizes the Composite/Component design pattern to store all elements that must be
28  * drawn on the SkyMap. In this design pattern, elements to be drawn in the map are called
29  * "Components", and they are hierarchically organized into groups called "Composites".
30  * A Composite can contain other Composites, as well as Components. From an organizational
31  * point of view, you can think of Composites and Components as being analogous to
32  * "Directories" and "Files" in a computer filesystem.
33  *
34  * The advantage of this design pattern is that it minimizes code duplication and maximizes
35  * modularity. There is a set of operations which all Components must perform periodically
36  * (such as drawing on screen, or updating position), but each Component may perform its task
37  * slightly differently. Thus, each Component can implement its own version of the functions,
38  * and each Composite calls on its child Components to execute the desired function. For
39  * example, if we wanted to draw all Components in the SkyMap, we would simply need to call
40  * "skyComposite()->draw()". SkyComposite is the "top-level" Composite; its "draw()" function
41  * simply calls draw() on each of its children. Its child Components will draw themselves,
42  * while its child Composites will call "draw()" for each of *their* children. Note that
43  * we don't need to know *any* implementation details; when we need to draw the
44  * elements, we just tell the top-level Composite to spread the word.
45  *
46  * \section ClassInheritance Class Inheritance
47  * The base class in this directory is SkyComponent; all other classes are derived from it
48  * (directly or indirectly). Its most important derivative is SkyComposite, the base classes
49  * for all Composites.
50  *
51  * FIXME: There is no SingleComponent
52  * From SkyComponent, we derive three important subclasses: SingleComponent, ListComponent,
53  * and PointListComponent. SingleComponent represents a sky element consisting of a single
54  * SkyObject, such as the Sun. ListComponent represents a list of SkyObjects, such as the
55  * Asteroids. PointListComponent represents a list of SkyPoints (not SkyObjects), such as
56  * the Ecliptic. Almost all other Components are derived from one of these three classes
57  * (two Components are derived directly from SkyComponent).
58  *
59  * The Solar System bodies require some special treatment. For example, only solar system
60  * bodies may have attached trails, and they move across the sky, so their positions must
61  * be updated frequently. To handle these features, we derive SolarSystemComposite from
62  * SkyComposite to be the container for all solar system Components. In addition, we derive
63  * SolarSystemSingleComponent from SingleComponent, and SolarSystemListComponent from
64  * ListComponent. These classes simply add functions to handle Trails, and to update the
65  * positions of the bodies. Also, they contain KSPlanetBase objects, instead of SkyObjects.
66  *
67  * The Sun, Moon and Pluto each get a unique Component class, derived from
68  * SolarSystemSingleComponent (this is needed because each of these bodies uses a unique
69  * class derived from KSPlanetBase: KSSun, KSMoon, and KSPluto). The remaining major
70  * planets are each represented with a PlanetComponent object, which is also derived from
71  * SolarSystemSingleComponent. Finally, we have AsteroidsComponent and CometsComponent,
72  * each of which is derived from SolarSystemListComponent.
73  *
74  * Next, we have the Components derived from PointListComponent. These Components represent
75  * imaginary guide lines in the sky, such as constellation boundaries or the coordinate grid.
76  * They are listed above, and most of them don't require further comment. The GuidesComposite
77  * contains two sub-Composites: CoordinateGridComposite, and ConstellationLinesComposite.
78  * Both of these contain a number of PointListComponents: CoordinateGridComposite contains one
79  * PointsListComponent for each circle in the grid, and ConstellationLineComposite contains
80  * one PointsListComponent for each constellation (representing the "stick figure" of the
81  * constellation).
82  *
83  * Finally, we have the Components which don't inherit from either SingleComponent,
84  * ListComponent, or PointListComponent: PlanetMoonsComponent inherits from SkyComponent
85  * directly, because the planet moons have their own class (PlanetMoons) not derived
86  * directly from a SkyPoint.
87  *
88  * \section StarComponent DeepStarComponent and StarComponent
89  * StarComponent and DeepStarComponent manage stars in KStars. StarComponent maintains a
90  * QVector of instances of DeepStarComponents and takes care of calling their draw routines
91  * etc. The machinery for handling stars is documented in great detail in \ref Stars
92  *
93  * @author Thomas Kabelmann
94  */
96 {
97  public:
98  /**
99  * @short Constructor
100  * @p parent pointer to the parent SkyComposite
101  */
102  explicit SkyComponent(SkyComposite *parent = nullptr);
103 
104  virtual ~SkyComponent() = default;
105 
106  /**
107  * @short Draw the object on the SkyMap
108  * @p skyp a pointer to the SkyPainter to use
109  */
110  virtual void draw(SkyPainter *skyp) = 0;
111 
112  /** @short Draw trails for objects. */
113  virtual void drawTrails(SkyPainter *skyp);
114 
115  /**
116  * @short Update the sky position(s) of this component.
117  *
118  * This function usually just updates the Horizontal (Azimuth/Altitude)
119  * coordinates of its member object(s). However, the precession and
120  * nutation must also be recomputed periodically.
121  * @p num Pointer to the KSNumbers object
122  * @sa SingleComponent::update()
123  * @sa ListComponent::update()
124  * @sa ConstellationBoundaryComponent::update()
125  */
126  virtual void update(KSNumbers *) {}
127  virtual void updateSolarSystemBodies(KSNumbers *) {}
128  virtual void updateMoons(KSNumbers *) {}
129 
130  /** @return true if component is to be drawn on the map. */
131  virtual bool selected()
132  {
133  return true;
134  }
135 
136  /** @return Parent of component. If there is no parent returns nullptr. */
138  {
139  return m_parent;
140  }
141 
142  /**
143  * @short Search the children of this SkyComponent for
144  * a SkyObject whose name matches the argument
145  * @p name the name to be matched
146  * @p exact If true, it will return an exact match, otherwise it can return
147  * a partial match.
148  * @return a pointer to the SkyObject whose name matches
149  * the argument, or a nullptr pointer if no match was found.
150  * @note This function simply returns the nullptr pointer; it
151  * is reimplemented in various sub-classes
152  */
153  virtual SkyObject *findByName(const QString &name, bool exact = true);
154 
155  /**
156  * @short Searches the region(s) and appends the SkyObjects found to the list of sky objects
157  *
158  * Look for a SkyObject that is in one of the regions
159  * If found, then append to the list of sky objects
160  * @p list list of SkyObject to which matching list has to be appended to
161  * @p region defines the regions in which the search for SkyObject should be done within
162  * @return void
163  * @note This function simply returns; it is
164  * reimplemented in various sub-classes.
165  */
166  virtual void objectsInArea(QList<SkyObject *> &list, const SkyRegion &region);
167 
168  /**
169  * @short Find the SkyObject nearest the given SkyPoint
170  *
171  * Look for a SkyObject that is nearer to point p than maxrad.
172  * If one is found, then maxrad is reset to the separation of the new nearest object.
173  * @p p pointer to the SkyPoint to search around
174  * @p maxrad reference to current search radius in degrees
175  * @return a pointer to the nearest SkyObject
176  * @note This function simply returns a nullptr pointer; it is
177  * reimplemented in various sub-classes.
178  */
179  virtual SkyObject *objectNearest(SkyPoint *p, double &maxrad);
180 
181  /**
182  * @short Emit signal about progress.
183  *
184  * @sa SkyMapComposite::emitProgressText
185  */
186  virtual void emitProgressText(const QString &message);
187 
188  inline QHash<int, QStringList> &objectNames()
189  {
190  return getObjectNames();
191  }
192 
193  inline QStringList &objectNames(int type)
194  {
195  return getObjectNames()[type];
196  }
197 
199  {
200  return getObjectLists();
201  }
202 
203  inline QVector<QPair<QString, const SkyObject *>> &objectLists(int type)
204  {
205  return getObjectLists()[type];
206  }
207 
208  void removeFromNames(const SkyObject *obj);
209  void removeFromLists(const SkyObject *obj);
210 
211  private:
212  virtual QHash<int, QStringList> &getObjectNames();
213  virtual QHash<int, QVector<QPair<QString, const SkyObject *>>> &getObjectLists();
214 
215  // Disallow copying and assignment
216  SkyComponent(const SkyComponent &);
217  SkyComponent &operator=(const SkyComponent &);
218 
219  /// Parent of sky component.
220  SkyComposite *m_parent;
221 };
virtual SkyObject * objectNearest(SkyPoint *p, double &maxrad)
Find the SkyObject nearest the given SkyPoint.
Stores dms coordinates for a point in the sky. for converting between coordinate systems.
Definition: skypoint.h:44
virtual void draw(SkyPainter *skyp)=0
Draw the object on the SkyMap skyp a pointer to the SkyPainter to use.
virtual void update(KSNumbers *)
Update the sky position(s) of this component.
Definition: skycomponent.h:126
virtual SkyObject * findByName(const QString &name, bool exact=true)
Search the children of this SkyComponent for a SkyObject whose name matches the argument name the nam...
virtual void objectsInArea(QList< SkyObject * > &list, const SkyRegion &region)
Searches the region(s) and appends the SkyObjects found to the list of sky objects.
SkyComposite * parent()
Definition: skycomponent.h:137
virtual void emitProgressText(const QString &message)
Emit signal about progress.
virtual bool selected()
Definition: skycomponent.h:131
Store several time-dependent astronomical quantities.
Definition: ksnumbers.h:42
Draws things on the sky, without regard to backend.
Definition: skypainter.h:37
VehicleSection::Type type(QStringView coachNumber, QStringView coachClassification)
SkyComponent(SkyComposite *parent=nullptr)
Constructor parent pointer to the parent SkyComposite.
virtual void drawTrails(SkyPainter *skyp)
Draw trails for objects.
Information about an object in the sky.
Definition: skyobject.h:41
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Wed Aug 17 2022 04:14:19 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.