[Kstars-devel] [kstars] /: Updating API documentation. Added missing INDI documentaion (only class documentation, member documentation TODO). Also added an overview of INDI with hierarchy and example case.
Jasem Mutlaq
mutlaqja at ikarustech.com
Wed Feb 11 22:41:01 UTC 2015
Git commit 7173763423766bdebb1d1635979eb3286c2e2619 by Jasem Mutlaq.
Committed on 11/02/2015 at 22:38.
Pushed by mutlaqja into branch 'master'.
Updating API documentation. Added missing INDI documentaion (only class documentation, member documentation TODO). Also added an overview of INDI with hierarchy and example case.
CCMAIL:kstars-devel at kde.org
M +3 -3 Mainpage.dox
M +1 -1 kstars/dialogs/addlinkdialog.h
M +2 -2 kstars/fitsviewer/fitsviewer.h
M +13 -5 kstars/indi/clientmanager.h
M +9 -4 kstars/indi/deviceinfo.h
M +24 -0 kstars/indi/driverinfo.h
M +14 -0 kstars/indi/drivermanager.h
M +7 -1 kstars/indi/guimanager.h
M +14 -0 kstars/indi/indiccd.h
M +75 -0 kstars/indi/indicommon.h
M +26 -18 kstars/indi/indidbus.h
M +5 -0 kstars/indi/indidevice.h
M +6 -4 kstars/indi/indielement.h
M +5 -0 kstars/indi/indifilter.h
M +6 -0 kstars/indi/indifocuser.h
M +5 -1 kstars/indi/indigroup.h
M +1 -3 kstars/indi/indilistener.cpp
M +11 -11 kstars/indi/indilistener.h
M +6 -1 kstars/indi/indiproperty.h
M +31 -1 kstars/indi/indistd.h
M +6 -3 kstars/indi/inditelescope.h
M +1 -1 kstars/indi/opsindi.ui
M +5 -0 kstars/indi/servermanager.h
M +1 -1 kstars/kstars.kcfg
M +1 -1 kstars/tools/astrocalc.h
http://commits.kde.org/kstars/7173763423766bdebb1d1635979eb3286c2e2619
diff --git a/Mainpage.dox b/Mainpage.dox
index f0d19de..141aacf 100644
--- a/Mainpage.dox
+++ b/Mainpage.dox
@@ -61,9 +61,9 @@ The "model" is encapsulated in the KStarsData class, and the "view" is encapsula
- KSAlmanac
\subsection Tools Tools
- - Calculator
- - FITSViewer
- - Devices
+ - \ref AstroCalc "Calculator": Calculator tool covering many astronomical calculations.
+ - FITSViewer: Open and preview FITS files.
+ - \ref INDI "Devices & INDI": Establish INDI drivers locally or connect to remote INDI servers.
- Ekos
- Sky Calender
- DetailDialog
diff --git a/kstars/dialogs/addlinkdialog.h b/kstars/dialogs/addlinkdialog.h
index 27e344f..34a82f1 100644
--- a/kstars/dialogs/addlinkdialog.h
+++ b/kstars/dialogs/addlinkdialog.h
@@ -34,7 +34,7 @@ public:
};
/**
- *@class Simple dialog for adding a custom URL to a popup menu.
+ *@class AddLinkDialog is a simple dialog for adding a custom URL to a popup menu.
*@author Jason Harris
*@version 1.0
*/
diff --git a/kstars/fitsviewer/fitsviewer.h b/kstars/fitsviewer/fitsviewer.h
index 0d96174..f3dbf57 100644
--- a/kstars/fitsviewer/fitsviewer.h
+++ b/kstars/fitsviewer/fitsviewer.h
@@ -52,8 +52,8 @@ class FITSDebayer;
/**
*@class FITSViewer
- *@short Primary window to open and process FITS images.
- * The FITS viewer can open multiple images each in a separate. It supports simple filters, histogram transforms, flip and roration operations, and star detection.
+ *@short Primary window to view monochrome and color FITS images.
+ * The FITSviewer can open multiple images each in a separate. It supports simple filters, histogram transforms, flip and roration operations, and star detection.
*@author Jasem Mutlaq
*@version 1.0
*/
diff --git a/kstars/indi/clientmanager.h b/kstars/indi/clientmanager.h
index 069e6ca..d236f92 100644
--- a/kstars/indi/clientmanager.h
+++ b/kstars/indi/clientmanager.h
@@ -1,6 +1,3 @@
-#ifndef CLIENTMANAGER_H
-#define CLIENTMANAGER_H
-
/* INDI Client Manager
Copyright (C) 2012 Jasem Mutlaq (mutlaqja at ikarustech.com)
@@ -9,7 +6,10 @@
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
- */
+*/
+
+#ifndef CLIENTMANAGER_H
+#define CLIENTMANAGER_H
#include <baseclient.h>
@@ -19,6 +19,15 @@ class DeviceInfo;
class DriverInfo;
class ServerManager;
+/**
+ * @class ClientManager manages connection to INDI server, creation of devices, and receving/sending properties.
+ *
+ * ClientManager is a subclass of INDI::BaseClient class part of the INDI Library.
+ * This enables the class to communicate with INDI server and to receive notification of devices, properties, and messages.
+ *
+ * @author Jasem Mutlaq
+ * @version 1.0
+ */
class ClientManager : public QObject, public INDI::BaseClient
{
Q_OBJECT
@@ -81,7 +90,6 @@ signals:
void INDIDeviceRemoved(DeviceInfo *dv);
-
};
#endif // CLIENTMANAGER_H
diff --git a/kstars/indi/deviceinfo.h b/kstars/indi/deviceinfo.h
index f957b7b..eec9522 100644
--- a/kstars/indi/deviceinfo.h
+++ b/kstars/indi/deviceinfo.h
@@ -1,6 +1,3 @@
-#ifndef DEVICEINFO_H
-#define DEVICEINFO_H
-
/* INDI Device Info
Copyright (C) 2012 Jasem Mutlaq (mutlaqja at ikarustech.com)
@@ -9,12 +6,20 @@
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
- */
+*/
+
+#ifndef DEVICEINFO_H
+#define DEVICEINFO_H
#include <basedevice.h>
#include "driverinfo.h"
+/**
+ * @class DeviceInfo Simple class to hold DriverInfo and INDI::BaseDevice associated with a particular device.
+ *
+ * @author Jasem Mutlaq
+ */
class DeviceInfo
{
public:
diff --git a/kstars/indi/driverinfo.h b/kstars/indi/driverinfo.h
index 4b9d793..09e9d03 100644
--- a/kstars/indi/driverinfo.h
+++ b/kstars/indi/driverinfo.h
@@ -21,6 +21,30 @@ class ServerManager;
class ClientManager;
class DeviceInfo;
+/**
+ * @class DriverInfo holds all metadata associated with a particular INDI driver.
+ * An INDI drivers holds both static and dynamic information. Example for static information:
+ * <ul>
+ * <li>Device name.</li>
+ * <li>Device label.</li>
+ * <li>Driver version.</li>
+ * <li>Device Family: Telescope, CCD, Focuser...etc</li>
+ *
+ * Dynamic information include associated Server and Client managers, port in use, associated devices...etc.
+ * Most INDI drivers operate only one device, but some driver can present multiple devices simultaneously.
+ *
+ * Driver information are obtained from multiple sources:
+ * <ol>
+ * <li>INDI driver XML file: All INDI driver install an XML file (usually to /usr/share/indi) that contains information
+ * on the driver and device or devices it is capabale of running.</li>
+ * <li>Client DriverInfos: Users can add a new host/port combo in the Device Manager in order to connect to
+ * to local or remote INDI servers.</li>
+ * <li>Generated DriverInfos: DriverInfo can be created programatically to connect to local or remote INDI server with unknown
+ * number of actual drivers/devices at the server side.
+ * </ol>
+ *
+ * @author Jasem Mutlaq
+ */
class DriverInfo : public QObject
{
Q_OBJECT
diff --git a/kstars/indi/drivermanager.h b/kstars/indi/drivermanager.h
index eeaea13..5ade6d1 100644
--- a/kstars/indi/drivermanager.h
+++ b/kstars/indi/drivermanager.h
@@ -51,6 +51,20 @@ public slots:
};
+/**
+ * @brief DriverManager is the primary class to handle all operations related to starting and stopping INDI drivers.
+ *
+ * INDI drivers can be local or remote drivers. For remote hosts, driver information is not known and devices are built
+ * as they arrive dynamically. The class parses INDI primary devices XML file (drivers.xml) and any 3rd party INDI Driver
+ * XML file to build a tree of devices grouped by driver family type.
+ *
+ * When starting local drivers, DriverManager also establishes an INDI server with the requested drivers and then connect to
+ * the local server to receive the devices dynamically.
+ *
+ * The class also handles INDI hosts which can be added in order to connect to a local or remote INDI server.
+ *
+ * @author Jasem Mutlaq
+ */
class DriverManager : public QDialog
{
diff --git a/kstars/indi/guimanager.h b/kstars/indi/guimanager.h
index 37a3efb..6fe03ff 100644
--- a/kstars/indi/guimanager.h
+++ b/kstars/indi/guimanager.h
@@ -43,7 +43,13 @@ class FITSViewer;
class INDI_D;
-
+/**
+ * @class GUIManager creates the INDI Control Panel upon receving a new device. Each device is displayed
+ * on a separate tab. The device and property GUI creation is performed dynamically via introspection. As new properties
+ * arrive from the ClientManager, they get created in the GUI.
+ *
+ * @author Jasem Mutlaq
+ */
class GUIManager : public QWidget
{
Q_OBJECT
diff --git a/kstars/indi/indiccd.h b/kstars/indi/indiccd.h
index 5e39a51..ecc7643 100644
--- a/kstars/indi/indiccd.h
+++ b/kstars/indi/indiccd.h
@@ -20,9 +20,17 @@ class FITSViewer;
class FITSData;
class StreamWG;
+/**
+ * \namespace ISD is collection of INDI Standard Devices. It encapsulates common type of INDI devices such as telescopes and CCDs.
+ *
+ */
namespace ISD
{
+/**
+ * @class CCDChip class controls a particular chip in CCD device. While most amateur CCDs only have a single chip on the CCD, some
+ * CCDs have additional chips targetted for guiding purposes.
+ */
class CCDChip
{
public:
@@ -101,6 +109,12 @@ private:
};
+/**
+ * @class CCD class controls an INDI CCD device. It can be used to issue and abort capture commands, receive and process BLOBs,
+ * and return information on the capabilities of the CCD.
+ *
+ * @author Jasem Mutlaq
+ */
class CCD : public DeviceDecorator
{
Q_OBJECT
diff --git a/kstars/indi/indicommon.h b/kstars/indi/indicommon.h
index 624d237..794c3f9 100644
--- a/kstars/indi/indicommon.h
+++ b/kstars/indi/indicommon.h
@@ -10,6 +10,81 @@
#ifndef INDICOMMON_H
#define INDICOMMON_H
+/*!
+\page INDI "INDI Overview"
+\tableofcontents
+
+\section Intro Introduction
+
+INDI is a simple XML-like communications protocol described for interactive and automated remote control of diverse instrumentation. INDI is small, easy to parse, and stateless.
+The main key concept in INDI is that devices have the ability to describe themselves. This is accomplished by using XML to describe a generic hierarchy that can represent both canonical and
+ non-canonical devices. All devices may contain one or more properties. A property in the INDI paradigm describes a specific function of the driver.
+Any property may contain one or more elements. There are four types of INDI properties:
+
+<ul>
+<li><b>Text property</b>: Property to transfer simple text information in ISO-8859-1. The text is not encoded or encrypted on transfer. If the text includes elements that can break XML syntax, a BLOB property should be used to make the transfer.</li>
+<li><b>Number property</b>: Property to transfer numeric information with configurable minimum, maximum, and step values. The supported number formats are decimal and sexigesmal. The property includes a GUI hint element in printf style format to enable clients to properly display numeric properties.</li>
+<li><b>Switch property</b>: Property to hold a group of options or selections (Represented in GUI by buttons and check boxes).</li>
+<li><b>Light property</b>: Property to hold a group of status indicators (Represented in GUI by colored LEDs).</li>
+<li><b>BLOB property</b>: BLOB is a Binary Large OBject used to transfer binary data to and from drivers.</li>
+</ul>
+
+For example, all INDI devices share the CONNECTION standard switch property. The CONNECTION property has two elements: CONNECT and DISCONNECT switches.
+GUI clients parse the generic XML description of properties and builds a GUI representation suitable for direct human interaction.
+
+KStars is a fully featured INDI client. INDI Data (i.e. devices and properties) and GUI (how they appear on the screen) are separated. INDI adopts is a server/client architecture where one or more servers
+communicate with one or more drivers, each driver can communicate with one or more actual hardware devices. Clients connect to the server, obtain a list of devices, and generate GUI to represent the
+devices for user interaction and control. The creation of GUI happens in run time via introspection.
+
+\section Structure Hierarchy
+
+The following is a description of some of the various classes that support INDI:
+
+<ul>
+<li>DriverManager: Manages local drivers as installed by INDI library. Enables users to start/stop local INDI servers (ServerManager) running one or more drivers (DriverInfo). Also enables connecting to local or remote
+INDI servers. For both local and remote connection, it creates a ClientManager to handle incoming data from each INDI server started, and creates a GUIManager to render the devices in INDI Control Panel.
+The user may also choose to only start an INDI server without a client manager and GUI.</li>
+<li>ClientManager: Manages sending and receving data from and to an INDI server. The ClientManager sends notifications (signals) when a new device or property is defined, updated, or deleted.</li>
+<li>GUIManager: Handles creation of GUI interface for devices (INDI_D) and their properties and updates the interface in accord with any data emitted by the associated ClientManager. The GUI manager supports
+multiple ClientManagers and consolidate all devices from all the ClientManagers into a single INDI Control Panel where each device is created as a tab.</li>
+<li>INDIListener: Once a ClientManager is created in DriverManager after successfully connecting to an INDI server, it is added to INDIListener where it monitors any new devices and if a new
+device is detected, it creates an ISD::GenericDevice to hold the data of the device. It also moniters new properties and registers them. If it detects an INDI standard property associated with a particular device family
+(e.g. Property EQUATORIAL_EOD_COORD is a standard property of a Telescope device), then it extends the ISD::GenericDevice to the particular specialized device type using the <a href="http://en.wikipedia.org/wiki/Decorator_pattern">
+Decorator Pattern</a>. All updated properties from INDI server are delegated to their respective devices.</li>
+<li>ServerManager</li> Manages establishment and shutdown of local INDI servers.</li>
+<li>DriverInfo</li>: Simple class that holds information on INDI drivers such as name, version, device type..etc.</li>
+<li>ISD::GDInterface: Abstract class where the ISD::DeviceDecorator and ISD::GenericDevice are derived.</li>
+<li>ISD::DeviceDecorator: Base class of all specialized decorators such as ISD::Telescope, ISD::Filter, and ISD::CCD devices.</li>
+<li>ISD::GenericDevice: Base class for all INDI devices. It implements processes shared across all INDI devices such as handling connection/disconnection, setting of configuration..etc.. When a
+specialized decorator is created (e.g. ISD::Telescope), the decorator is passed an ISD::GenericDevice pointer. Since ISD::Telescope is a child of ISD::DeviceDecorator, it can override some or all
+ the device specific functions as defined in ISD::GDInterface (e.g. ProcessNumber(INumberVectorProperty *nvp)). For any function that is not overridden, the parent ISD::DeviceDecorator will invoke
+ the function in ISD::GenericDevice instead. Moreover, The specialized decorator device can explicity call DeviceDecorator::ProcessNumber(INumberVectorProperty *nvp) for example to cause the ISD::DeviceDecorator to invoke
+ the same function but as defined in ISD::GenericDevice.</li>
+ </ul>
+
+\section Example Example
+
+Suppose the user wishes to control an EQMod mount with \e indi_eqmod_telescope driver. From the DriverManager GUI, the user selects the driver and \e starts INDI services. The DriverManager
+will create a ServerManager instance to run an INDI server with the EQMod driver executable. After establishing the server, the DriverManager will create an instance of ClientManager and set
+its INDI server address as the host and port of the server created in ServerManager. For local servers, the host name is \e localhost and the default INDI port is 7624. If connection to the INDI server
+is successful, DriverManager then adds the ClientManager to both INDIListener (to handle data), and GUIManager (to handle GUI). Since the ClientManager emits signals whenever a new, updated, or deleted
+device/property is received from INDI server, it affects both the data handling part as well as GUI rendering.
+
+INDIListener holds a list of all INDI devices in KStars regardless of their origin. Once INDIListener receives a new device from the ClientManager, it creates a new ISD::GenericDevice. At the GUIManager side, it creates INDI Control Panel and adds a new tab with the device name.
+It also creates a separate tab for each property group received. The user is presented with a basic GUI to set the connection port of EQMod and to connect/disconnect to/from the telescope. If the
+user clicks connect, the status of the connection property is updated, and INDI_P sends the new switch status (CONNECT=ON) to INDI server via the ClientManager. If the connection is successful
+at the driver side, it will start defining new properties to cover the complete functionality of the EQMod driver, one of the standard properties is EQUATORIAL_EOD_COORD which will be detected
+in INDIListener. Upon detection of this key signature property, INDIListener creates a new ISD::Telescope device while passing to it the ISD::GenericDevice instance created earliar.
+
+Now suppose an updated Number property arrives from INDI server, the ClientManager emits a signal indicating a number property has a new updated value and INDIListener delegates the INDI Number
+property to the device, which is now of type ISD::Telescope. The ISD::Telescope overridden the processNumber(INumberVectorProperty *nvp) function in ISD::DeviceDecorator because it wants to handle some telescope
+specific numbers such as EQUATORIAL_EOD_COORD in order to move the telescope marker on the sky map as it changes. If the receieved property was indeed EQUATORIAL_EOD_COORD or any property handled
+by the ISD::Telescope ProcessNumber() function, then there is no futher action needed. But what if the property is not processed in ISD::Telescope ProcessNumber() function? In this case, the
+ProcessNumber() function simply calls DeviceDecorator::ProcessNumber() and it will delgate the call to ISD::GenericDevice ProcessNumber() to process. This is how the Decorator pattern work,
+the decorator classes implements extended functionlity, but the basic class is still responsible for handling all of the basic functions.
+
+*/
+
#define INDIVERSION 1.7 /* we support this or less */
typedef enum { PRIMARY_XML, THIRD_PARTY_XML, EM_XML, HOST_SOURCE, GENERATED_SOURCE } DriverSource;
diff --git a/kstars/indi/indidbus.h b/kstars/indi/indidbus.h
index 4c50024..1836f6a 100644
--- a/kstars/indi/indidbus.h
+++ b/kstars/indi/indidbus.h
@@ -21,55 +21,61 @@ class INDIDBUS : public QObject
public:
explicit INDIDBUS(QObject *parent = 0);
- /**DBUS interface function. Start server locally on the given port and drivers list
+ /** @defgroup INDIDBusInterface INDI DBus Interface
+ * INDIDBus interface provides complete scripting capability over INDI servers and devices within KStars.
+ */
+
+ /*@{*/
+
+ /** DBUS interface function. Start a local INDI server given a list of drivers on the given port.
* @param port Port used to establish server. If empty, default port 7624 is used.
- * @param drivers List of drivers executables to run
+ * @param drivers List of drivers executables to run.
*/
Q_SCRIPTABLE bool start (const QString &port, const QStringList &drivers);
- /**DBUS interface function. Stops server running on the given port
+ /** DBUS interface function. Stops server running on the given port
@param port Port of existing server to stop
*/
Q_SCRIPTABLE bool stop (const QString &port);
- /**DBUS interface function. Connect to an server
+ /** DBUS interface function. Connect to an INDI server
* @host hostname of server to connect to.
* @param port Port of server.
*/
Q_SCRIPTABLE bool connect (const QString &host, const QString &port);
- /**DBUS interface function. Disconnect from an server
+ /** DBUS interface function. Disconnect from an INDI server
* @host hostname of server to disconnect.
* @param port Port of server.
*/
Q_SCRIPTABLE bool disconnect (const QString &host, const QString &port);
- /**DBUS interface function. Returns a list of devices
+ /** DBUS interface function. Returns a list of INDI devices
* @returns List of device names
*/
Q_SCRIPTABLE QStringList getDevices();
- /**DBUS interface function. Returns a list of properties
+ /** DBUS interface function. Returns a list of INDI properties
* @device device name
* @returns List of properties in the format DEVICE.PROPERTY.ELEMENT.
*/
Q_SCRIPTABLE QStringList getProperties(const QString &device);
- /**DBUS interface function. Returns property state
+ /** DBUS interface function. Returns INDI property state
* @device device name
* @property property name
* @returns Idle, Ok, Busy, or Alert. If no property is found, it returns "Invalid"
*/
Q_SCRIPTABLE QString getPropertyState(const QString &device, const QString &property);
- /**DBUS interface function. Sends property to server
+ /** DBUS interface function. Sends property to INDI server
* @device device name
* @property property name
* @returns true if property is found and sent to server, false otherwise.
*/
Q_SCRIPTABLE bool sendProperty(const QString &device, const QString &property);
- /**DBUS interface function. Set Switch status
+ /** DBUS interface function. Set INDI Switch status
* @device device name
* @property property name
* @switchName switch name
@@ -78,7 +84,7 @@ public:
*/
Q_SCRIPTABLE bool setSwitch(const QString &device, const QString &property, const QString &switchName, const QString &status);
- /**DBUS interface function. Returns switch status
+ /** DBUS interface function. Returns INDI switch status
* @device device name
* @property property name
* @switchName switch name
@@ -86,7 +92,7 @@ public:
*/
Q_SCRIPTABLE QString getSwitch(const QString &device, const QString &property, const QString &switchName);
- /**DBUS interface function. Set Text
+ /** DBUS interface function. Set INDI Text
* @device device name
* @property property name
* @textName text element name
@@ -95,7 +101,7 @@ public:
*/
Q_SCRIPTABLE bool setText(const QString &device, const QString &property, const QString &textName, const QString &text);
- /**DBUS interface function. Returns text value
+ /** DBUS interface function. Returns INDI text value
* @device device name
* @property property name
* @textName text element name
@@ -103,7 +109,7 @@ public:
*/
Q_SCRIPTABLE QString getText(const QString &device, const QString &property, const QString &textName);
- /**DBUS interface function. Set Number
+ /** DBUS interface function. Set INDI Number
* @device device name
* @property property name
* @NumberName number element name
@@ -112,7 +118,7 @@ public:
*/
Q_SCRIPTABLE bool setNumber(const QString &device, const QString &property, const QString &numberName, double value);
- /**DBUS interface function. Returns number value
+ /** DBUS interface function. Returns INDI number value
* @device device name
* @property property name
* @numberName number element name
@@ -120,7 +126,7 @@ public:
*/
Q_SCRIPTABLE double getNumber(const QString &device, const QString &property, const QString &numberName);
- /**DBUS interface function. Returns Light state
+ /** DBUS interface function. Returns INDI Light state
* @device device name
* @property property name
* @lightName light element name
@@ -128,17 +134,18 @@ public:
*/
Q_SCRIPTABLE QString getLight(const QString &device, const QString &property, const QString &lightName);
- /**DBUS interface function. Returns blob data. It can be extremely inefficient transporting large amount of data via DBUS.
+ /** DBUS interface function. Returns INDI blob data. It can be extremely inefficient transporting large amount of data via DBUS.
* @device device name
* @property property name
* @blobName blob element name
* @blobFormat blob element format. It is usually the extension of the blob file.
* @size blob element size in bytes. If -1, then there is an error.
* @returns array of bytes containing blob.
+ * @see getBLOBFile
*/
Q_SCRIPTABLE QByteArray getBLOBData(const QString &device, const QString &property, const QString &blobName, QString &blobFormat, int & size);
- /**DBUS interface function. Returns blob filename stored on the local file system.
+ /** DBUS interface function. Returns INDI blob filename stored on the local file system.
* @device device name
* @property property name
* @blobName blob element name
@@ -148,6 +155,7 @@ public:
*/
Q_SCRIPTABLE QString getBLOBFile(const QString &device, const QString &property, const QString &blobName, QString &blobFormat, int & size);
+ /** @}*/
};
diff --git a/kstars/indi/indidevice.h b/kstars/indi/indidevice.h
index d368516..6d0ea23 100644
--- a/kstars/indi/indidevice.h
+++ b/kstars/indi/indidevice.h
@@ -27,6 +27,11 @@ class GUIManager;
class ClientManager;
class INDI_G;
+/**
+ * @class INDI_D represents an INDI GUI Device. INDI_D is the top level device container. It contains a collection of groups of properties. Each group is represented as a separate tab within the GUI.
+ *
+ * @author Jasem Mutlaq
+ */
class INDI_D : public QDialog
{
Q_OBJECT
diff --git a/kstars/indi/indielement.h b/kstars/indi/indielement.h
index 4689b3e..cf5868b 100644
--- a/kstars/indi/indielement.h
+++ b/kstars/indi/indielement.h
@@ -40,7 +40,12 @@ class QSlider;
class INDI_P;
-/* INDI Element */
+/**
+ * @class INDI_E represents an INDI GUI element (Number, Text, Switch, Light, or BLOB) within an INDI property. It is the most basic
+ * GUI representation of property elements.
+ *
+ * @author Jasem Mutlaq
+ */
class INDI_E : public QObject
{
Q_OBJECT
@@ -62,8 +67,6 @@ public:
void buildLight(ILight *ilp);
void buildBLOB(IBLOB *ibp);
-
-
// Updates GUI from data in INDI properties
void syncSwitch();
void syncText();
@@ -76,7 +79,6 @@ public:
void setText(const QString & newText);
-
void setMin ();
void setMax ();
diff --git a/kstars/indi/indifilter.h b/kstars/indi/indifilter.h
index d8d915e..ea3a8b7 100644
--- a/kstars/indi/indifilter.h
+++ b/kstars/indi/indifilter.h
@@ -15,6 +15,11 @@
namespace ISD
{
+/**
+ * @class Filter class handles control of INDI Filter devices.
+ *
+ * @author Jasem Mutlaq
+ */
class Filter : public DeviceDecorator
{
Q_OBJECT
diff --git a/kstars/indi/indifocuser.h b/kstars/indi/indifocuser.h
index 3786eab..0d93017 100644
--- a/kstars/indi/indifocuser.h
+++ b/kstars/indi/indifocuser.h
@@ -15,6 +15,12 @@
namespace ISD
{
+/**
+ * @class Focuser class handles control of INDI focuser devices. Both relative and absolute focusers can be controlled.
+ *
+ * @author Jasem Mutlaq
+ */
+
class Focuser : public DeviceDecorator
{
Q_OBJECT
diff --git a/kstars/indi/indigroup.h b/kstars/indi/indigroup.h
index c3756ec..9a1b510 100644
--- a/kstars/indi/indigroup.h
+++ b/kstars/indi/indigroup.h
@@ -28,7 +28,11 @@ class QVBoxLayout;
class QSpacerItem;
class QScrollArea;
-/* INDI group */
+/**
+ * @class INDI_G represents a collection of INDI properties that share a common group. The group is usually represented in the GUI as a separate tab with the device tab.
+ *
+ * @author Jasem Mutlaq
+ */
class INDI_G
{
public:
diff --git a/kstars/indi/indilistener.cpp b/kstars/indi/indilistener.cpp
index fb79b19..d45e430 100644
--- a/kstars/indi/indilistener.cpp
+++ b/kstars/indi/indilistener.cpp
@@ -53,9 +53,7 @@ INDIListener * INDIListener::Instance()
INDIListener::INDIListener()
{
- batchMode = false;
- ISOMode = true;
- fv = NULL;
+
}
bool INDIListener::isStandardProperty(const QString &name)
diff --git a/kstars/indi/indilistener.h b/kstars/indi/indilistener.h
index fb3d28f..d9079ea 100644
--- a/kstars/indi/indilistener.h
+++ b/kstars/indi/indilistener.h
@@ -21,6 +21,15 @@ class ClientManager;
class FITSViewer;
class DeviceInfo;
+/**
+ * @class INDIListener is responsible for creating ISD::GDInterface generic devices as new devices arrive from ClientManager. It can support multiple ClientManagers
+ * and will first create a generic INDI device. Upon arrival of INDI properties, INDIListener can create specialized devices (e.g. Telescope) if it detects key Standard INDI
+ * property that signifies a particular device family. The generic device functionality is extended via the Decorator design pattern.
+ *
+ * INDIListener also delegates INDI properties as they are received from ClientManager to the appropiate device to be processed.
+ *
+ * @author Jasem Mutlaq
+ */
class INDIListener : public QObject
{
Q_OBJECT
@@ -31,16 +40,12 @@ public:
void addClient(ClientManager *cm);
void removeClient(ClientManager *cm);
- void setISOMode(bool enable) { ISOMode = enable; }
- void setBatchMode(bool enable) { batchMode = enable; }
-
+ ISD::GDInterface * getDevice(const QString &name);
QList<ISD::GDInterface *> getDevices() { return devices; }
int size() { return devices.size(); }
- bool isStandardProperty(const QString &name);
-
- ISD::GDInterface * getDevice(const QString &name);
+ bool isStandardProperty(const QString &name);
private:
INDIListener();
@@ -49,11 +54,6 @@ public:
QList<ISD::GDInterface *> devices;
QList<ISD::ST4*> st4Devices;
- bool batchMode;
- bool ISOMode;
-
- FITSViewer * fv;
-
public slots:
void registerProperty(INDI::Property *prop);
diff --git a/kstars/indi/indiproperty.h b/kstars/indi/indiproperty.h
index 06189a4..98de4c5 100644
--- a/kstars/indi/indiproperty.h
+++ b/kstars/indi/indiproperty.h
@@ -32,7 +32,12 @@ class QButtonGroup;
class QAbstractButton;
class QCheckBox;
-/* INDI property */
+/**
+ * @class INDI_P represents a single INDI property (Switch, Text, Number, Light, or BLOB). It handles building the GUI and updating the property status and/or value as new data
+ * arrive from INDI Serve. It also sends any changes in the property value back to INDI server via the ClientManager.
+ *
+ * @author Jasem Mutlaq
+ */
class INDI_P : public QObject
{
Q_OBJECT
diff --git a/kstars/indi/indistd.h b/kstars/indi/indistd.h
index d4fcb64..139393f 100644
--- a/kstars/indi/indistd.h
+++ b/kstars/indi/indistd.h
@@ -44,6 +44,15 @@ public:
};
+/**
+ * @class GDInterface is the Generic Device <i>Interface</i> for INDI devices. It is used as part of the Decorater Pattern when initally a new INDI device is created as a
+ * Generic Device in INDIListener. If the device registers an INDI Standard Property belonging to one specific device type (e.g. Telescope), then the device functionality
+ * is extended to the particular device type.
+ *
+ * DeviceDecorator subclasses GDInterface and calls concrete decorators methods.
+ *
+ * @author Jasem Mutlaq
+ */
class GDInterface : public QObject
{
Q_OBJECT
@@ -100,9 +109,17 @@ signals:
};
+/**
+ * @class GenericDevice is the Generic Device for INDI devices. When a new INDI device is created in INDIListener, it gets created as a GenericDevice initially. If the device
+ * registers a standard property that is a key property to a device type family (e.g. Number property EQUATORIAL_EOD_COORD signifies a Telescope device), then the specialized version of
+ * the device is exnteded via the Decorater Pattern.
+ *
+ * GenericDevice handles common functions shared across many devices such as time and location handling, configuration processing, retrieving information about properties, driver info..etc.
+ *
+ * @author Jasem Mutlaq
+ */
class GenericDevice : public GDInterface
{
-
Q_OBJECT
public:
@@ -152,6 +169,11 @@ private:
};
+/**
+ * @class DeviceDecorator is the base decorater for all specialized devices. It extends the functionality of GenericDevice.
+ *
+ * @author Jasem Mutlaq
+ */
class DeviceDecorator : public GDInterface
{
Q_OBJECT
@@ -197,6 +219,14 @@ protected:
};
+/**
+ * @class ST4 is a special class that handles ST4 commands. Since ST4 functionalty can be part of a stand alone ST4 device,
+ * or as part of a larger device as CCD or Telescope, it is handled separately to enable one ST4 device regardless of the parent device type.
+ *
+ * ST4 is a hardware port dedicated to sending guiding correction pulses to the mount.
+ *
+ * @author Jasem Mutlaq
+ */
class ST4
{
public:
diff --git a/kstars/indi/inditelescope.h b/kstars/indi/inditelescope.h
index 3778da7..9d31f20 100644
--- a/kstars/indi/inditelescope.h
+++ b/kstars/indi/inditelescope.h
@@ -15,7 +15,12 @@
namespace ISD
{
-
+/**
+ * @class Telescope device handle controlling telescope. It can slew and sync to a specific sky point and supports all standard propreties with INDI
+ * telescope device.
+ *
+ * @author Jasem Mutlaq
+ */
class Telescope : public DeviceDecorator
{
Q_OBJECT
@@ -52,14 +57,12 @@ public:
protected:
bool sendCoords(SkyPoint *ScopeTarget);
-
public slots:
virtual bool runCommand(int command, void *ptr=NULL);
bool Abort();
bool Park();
private:
-
SkyPoint currentCoord;
};
diff --git a/kstars/indi/opsindi.ui b/kstars/indi/opsindi.ui
index 108829b..af511fd 100644
--- a/kstars/indi/opsindi.ui
+++ b/kstars/indi/opsindi.ui
@@ -364,7 +364,7 @@
<string>Single Window FITS</string>
</property>
<property name="checked">
- <bool>true</bool>
+ <bool>false</bool>
</property>
</widget>
</item>
diff --git a/kstars/indi/servermanager.h b/kstars/indi/servermanager.h
index cd37118..b596865 100644
--- a/kstars/indi/servermanager.h
+++ b/kstars/indi/servermanager.h
@@ -23,6 +23,11 @@
class DriverInfo;
+/**
+ * @class ServerManager is responsible for starting and shutting local INDI servers.
+ *
+ * @author Jasem Mutlaq
+ */
class ServerManager : public QObject
{
diff --git a/kstars/kstars.kcfg b/kstars/kstars.kcfg
index bf4cf86..97fd308 100644
--- a/kstars/kstars.kcfg
+++ b/kstars/kstars.kcfg
@@ -150,7 +150,7 @@
<entry name="singleWindowFITS" type="Bool">
<label>Display all FITS in one window?</label>
<whatsthis>Display all captured FITS images in a single FITS Viewer window. By default each camera create its own FITS Viewer instance</whatsthis>
- <default>true</default>
+ <default>false</default>
</entry>
<entry name="telescopePort" type="String">
<label>INDI Telescope port</label>
diff --git a/kstars/tools/astrocalc.h b/kstars/tools/astrocalc.h
index 5dd929f..6c04599 100644
--- a/kstars/tools/astrocalc.h
+++ b/kstars/tools/astrocalc.h
@@ -28,7 +28,7 @@ class QTreeWidget;
class QTreeWidgetItem;
class QTextEdit;
-/** Astrocalc is the base class for the KStars astronomical calculator
+/** @class AstroCalc is the base class for the KStars astronomical calculator
* @author: Pablo de Vicente
* @version 0.9
*/
More information about the Kstars-devel
mailing list