Changeset 302:a4e4cda5d89a

Timestamp:

08/03/12 14:14:32 (12 years ago)

Author:

István Váradi <ivaradi@…>

Branch:

default

Phase:

public

Message:

Added overview documentation

Files:

• doc/overview.dox (modified) (2 diffs)
• src/mlx/gui/common.py (modified) (1 diff)

doc/overview.dox

@@ -8 +8 @@
  * 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
@@ -50 +54 @@
  * \li To create install packages, you also need py2exe: <a href="http://www.py2exe.org/">http://www.py2exe.org</a>,
  * \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. 
  */
  

src/mlx/gui/common.py

@@ -18 +18 @@
 # Windows or when the \c FORCE_PYGTK environment variable is set.
 #
-# Besides this there some common utility classes and functions.
+# Besides this there are some common utility classes and functions.
 
 #-----------------------------------------------------------------------------