/*! \mainpage MAVA Logger X Developers' Documentation
*
* \section intro Introduction
*
* This (partially generated) documentation describes the MAVA Logger
* X from a developer's perspective. Its purpose is to give enough
* information, so that a developer could understand how the software
* works in general, and easily understand the code to be able to make
* modifications to it.
*
* Note, that to be able to understand the code most effectively, it
* is important to either use the application actively, or to read its
* user documentation carefully.
*
* \section overview Overview
*
* The application was written in
* Python 2. The Python wrapper
* Gtk+ toolkit was used for the graphical
* user interface. The program is designed to run on both Windows and
* Linux, though as of this writing only the Windows version can be
* used practically. However, Linux distributions move towards Gtk+ 3
* as the primary toolkit, while it has no reliable port for Windows
* yet. Therefore it was decided to support both Gtk+ 2 and 3
* depending on the platform. For Gtk+ 2 the
* PyGTK wrapper is used, while for Gtk+
* 3 the PyGObject
* bindings. See the mlx.gui.common module for information on how the
* differences between these toolkits are handled.
*
* At present only Microsoft Flight Simulator 2004 and X (also,
* perhaps, Prepar3D) are supported, and are accessed via the
* FSUIPC
* interface. The author has created a Python mapping for it, which
* has been submitted for inclusion into the SDK, so it will hopefully
* appear in its next version. It is planned to support X-Plane in the
* near future (hopefully by the end of 2012) on both Linux and
* Windows.
*
* \subsection overview_devenv Development environment
*
* The software is primarily being developed on Linux, but is possible
* to perform development on Windows as well. You need to have Python
* 2.7.x installed as well as one of the above mentioned wrappers for
* Gtk+ and Gtk+ itself. Since Python is an interpreted language,
* there is no need for any special build system.
*
* Python and Gtk+ are readily available on most Linux distributions,
* but some links are probably useful for Windows users:
* \li Python has its own Windows installers: http://www.python.org/download/releases
* \li PyGTK provides convenient all-in-one installers including Gtk+
* itself: http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.24
* \li The Windows version uses some Python extensions: http://sourceforge.net/projects/pywin32/files
* \li To create install packages, you also need py2exe: http://www.py2exe.org,
* \li as well as the Nullsoft Install System: http://nsis.sourceforge.net/Main_Page
*
* The install package can be created by running the \c makeinst.bat
* file. It contains some absolute paths, so check those befure
* running the batch file. Windows is needed currently to create an
* install package.
*
* On Linux you can use the \c makesdist.sh script to create the
* archive that you can extract on Windows. This archive goes in to
* the \c dist subdirectory, and contains everything needed (from the
* logger) to create the package.
*
* \section arch Architecture
*
* The two major parts of the application are the GUI and the rest of
* it (let's call it the "business logic").
* The main interface for the GUI is the mlx.gui.gui.GUI class, which
* is referenced from the business logic only from the
* mlx.flight.Flight class. The rest of the business logic uses the
* actual instance of this class to access values entered into the
* GUI by the user.
*
* The program uses a few threads. The main thread is reserved for the
* GUI, which has two implications:
*
* -# No GUI operations should be executed directly from another
* thread. Instead, use \c gobject.idle_add to "inject" the
* operation into the main thread.
* -# To ensure the responsiveness of the GUI, only operations
* that take a short time should be executed in the GUI thread.
*
* \subsection arch_buslog Business Logic
*
* The business logic part deals with the connection towards the
* simulator. The mlx.fsuipc module implements this connection using
* the FSUIPC interface. Its \ref mlx.fsuipc.Simulator "Simulator"
* class creates a \ref mlx.fsuipc.Handler "Handler" object, which
* starts its own thread, in which the FSUIPC requests are called. In
* case of reading data from FSUIPC, the data is passed to a callback
* function, which is called in this thread. This should be considered
* when the retrieved data is processed on the GUI in same way
* (e.g. displayed). The main interface towards the simulator is the
* \ref mlx.fsuipc.Simulator "Simulator" class, so if another
* simulator is to be supported, a class with the same (or at least
* sufficiently similar) public interface should be implemented.
*
* The most important function of the program is the
* continuous monitoring of the aircraft's parameters and some other
* data. The monitoring is started using the \ref
* mlx.fsuipc.Simulator.startMonitoring "startMonitoring" function of
* the simulator object. If started, it calls the \ref
* mlx.acft.Aircraft.handleState "handleState" function of the
* mlx.acft.Aircraft instance used. The mlx.acft module contains one
* child class of \ref mlx.acft.Aircraft "Aircraft" for each aircraft
* type in the MAVA fleet. These subclasses contain the type-specific
* behaviour, but the main handling logic is in the \ref
* mlx.acft.Aircraft "Aircraft" class.
*
* Upon calling its \c handleState function, it calculates the
* smoothed values of IAS and VS, and then calls each "checker". A
* checker is an instance of a subclass of mlx.checks.StateChecker,
* which checks a one or a few parameters that are important from some
* aspect of the correct execution of a flight. For example, a checker
* may check if the \ref mlx.checks.StrobeLightsChecker
* "strobe lights" are switched on and off at the right stages of the
* flight. But some checkers simply log some \ref
* mlx.checks.AltimeterLogger "value" whenever it changes
* in an "interesting" way, or \ref mlx.checks.ACARSSender "send the
* ACARS" periodically.
*
* There is also a \ref mlx.checks.StageCheker "checker" which
* detects the changes in the stage of the flight, and calls the
* \ref mlx.acft.Aircraft.setStage "setStage" function of the
* aircraft, if there is a change. It first calls the
* \ref mlx.flight.Flight "flight"'s \ref mlx.flight.Flight.setStage
* "setStage" function, which notifies the GUI and the \ref
* mlx.logger.Logger "logger" of this change, and records the block
* and flight times. Then the aircraft's \c setStage function logs
* some values in case of certain stages, such as the takeoff weights
* and speeds when the takeoff stage is entered. After calling the
* checkers, the \c handleState function of the aircraft calls the
* \ref mlx.flight.Flight.handleState "function" with the same name of
* the flight. It again records some statistical data, such as the
* flown distance and the amount of fuel used, and calls the \ref
* mlx.soundsched.SoundScheduler "sound scheduler" to check if some
* backround sound should be played. If the check list hotkey is
* pressed, the \ref mlx.soundsched.ChecklistScheduler
* "checklist scheduler" is notified too.
*
* As mentioned, there is a \ref mlx.logger.Logger "logger" in the
* application, which contains the textual log lines as well as the
* faults and their scores.
*
* The business logic part contains many other components, but they
* are quite simple and are built around the principles mentioned
* above. Consult the documentation and the code of the relevant
* modules for more information.
*
* \subsection arch_gui GUI
*
* As mentioned, the GUI is implemented using Gtk+. This toolkit
* provides the Glade graphical user interface designer, but due to
* the requirement of supporting both Gtk+ 2 and 3, and due to a so-so
* experience with Glade in an earlier project, it was decided to not
* use it. Instead, the GUI elements are created and handled by
* hand-written code.
*
* The central class of the graphical user interface is
* mlx.gui.gui.GUI. Upon creation, it creates the rest of the GUI,
* sets up the menus and shortcuts, etc. It also maintains the
* connection to the simulator and creates the \ref mlx.flight.Flight
* "flight" and \ref mlx.flight.Aircraft "aircraft" objects as
* needed.
*
* To understand the operation of the GUI, one should be familiar with
* Gtk+, but otherwise it is pretty straighforward. See the
* documentation of the relevant modules for more information.
*/