Kstars

skycomponent.h
1/*
2 SPDX-FileCopyrightText: 2005 Thomas Kabelmann <thomas.kabelmann@gmx.de>
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
12class QString;
13
14class SkyObject;
15class SkyPoint;
16class SkyComposite;
17class 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();
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};
There are several time-dependent values used in position calculations, that are not specific to an ob...
Definition ksnumbers.h:43
SkyComponent represents an object on the sky map.
virtual void draw(SkyPainter *skyp)=0
Draw the object on the SkyMap skyp a pointer to the SkyPainter to use.
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()
virtual void drawTrails(SkyPainter *skyp)
Draw trails for objects.
virtual SkyObject * objectNearest(SkyPoint *p, double &maxrad)
Find the SkyObject nearest the given SkyPoint.
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 update(KSNumbers *)
Update the sky position(s) of this component.
virtual bool selected()
SkyComponent(SkyComposite *parent=nullptr)
Constructor parent pointer to the parent SkyComposite.
virtual void emitProgressText(const QString &message)
Emit signal about progress.
SkyComposite is a kind of container class for SkyComponent objects.
Provides all necessary information about an object in the sky: its coordinates, name(s),...
Definition skyobject.h:42
Draws things on the sky, without regard to backend.
Definition skypainter.h:40
The sky coordinates of a point in the sky.
Definition skypoint.h:45
VehicleSection::Type type(QStringView coachNumber, QStringView coachClassification)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 4 2024 12:01:03 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.