Changeset 302:a4e4cda5d89a


Ignore:
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:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/overview.dox

    r301 r302  
    88 * works in general, and easily understand the code to be able to make
    99 * modifications to it.
     10 *
     11 * Note, that to be able to understand the code most effectively, it
     12 * is important to either use the application actively, or to read its
     13 * user documentation carefully.
    1014 *
    1115 * \section overview Overview
     
    5054 * \li To create install packages, you also need py2exe: <a href="http://www.py2exe.org/">http://www.py2exe.org</a>,
    5155 * \li as well as the Nullsoft Install System: http://nsis.sourceforge.net/Main_Page
     56 *
     57 * The install package can be created by running the \c makeinst.bat
     58 * file. It contains some absolute paths, so check those befure
     59 * running the batch file. Windows is needed currently to create an
     60 * install package.
     61 *
     62 * On Linux you can use the \c makesdist.sh script to create the
     63 * archive that you can extract on Windows. This archive goes in to
     64 * the \c dist subdirectory, and contains everything needed (from the
     65 * logger) to create the package.
     66 *
     67 * \section arch Architecture
     68 *
     69 * The two major parts of the application are the GUI and the rest of
     70 * it (let's call it the "business logic").
     71 * The main interface for the GUI is the mlx.gui.gui.GUI class, which
     72 * is referenced from the business logic only from the
     73 * mlx.flight.Flight class. The rest of the business logic uses the
     74 * actual instance of this class to access values entered into the
     75 * GUI by the user.
     76 *
     77 * The program uses a few threads. The main thread is reserved for the
     78 * GUI, which has two implications:
     79 *
     80 * -# No GUI operations should be executed directly from another
     81 *    thread. Instead, use \c gobject.idle_add to "inject" the
     82 *    operation into the main thread.
     83 * -# To ensure the responsiveness of the GUI, only operations
     84 *    that take a short time should be executed in the GUI thread.
     85 *
     86 * \subsection arch_buslog Business Logic
     87 *
     88 * The business logic part deals with the connection towards the
     89 * simulator. The mlx.fsuipc module implements this connection using
     90 * the FSUIPC interface. Its \ref mlx.fsuipc.Simulator "Simulator"
     91 * class creates a \ref mlx.fsuipc.Handler "Handler" object, which
     92 * starts its own thread, in which the FSUIPC requests are called. In
     93 * case of reading data from FSUIPC, the data is passed to a callback
     94 * function, which is called in this thread. This should be considered
     95 * when the retrieved data is processed on the GUI in same way
     96 * (e.g. displayed). The main interface towards the simulator is the
     97 * \ref mlx.fsuipc.Simulator "Simulator" class, so if another
     98 * simulator is to be supported, a class with the same (or at least
     99 * sufficiently similar) public interface should be implemented.
     100 *             
     101 * The most important function of the program is the
     102 * continuous monitoring of the aircraft's parameters and some other
     103 * data. The monitoring is started using the \ref
     104 * mlx.fsuipc.Simulator.startMonitoring "startMonitoring" function of
     105 * the simulator object. If started, it calls the \ref
     106 * mlx.acft.Aircraft.handleState "handleState" function of the
     107 * mlx.acft.Aircraft instance used. The mlx.acft module contains one
     108 * child class of \ref mlx.acft.Aircraft "Aircraft" for each aircraft
     109 * type in the MAVA fleet. These subclasses contain the type-specific
     110 * behaviour, but the main handling logic is in the \ref
     111 * mlx.acft.Aircraft "Aircraft" class.
     112 *
     113 * Upon calling its \c handleState function, it calculates the
     114 * smoothed values of IAS and VS, and then calls each "checker". A
     115 * checker is an instance of a subclass of mlx.checks.StateChecker,
     116 * which checks a one or a few parameters that are important from some
     117 * aspect of the correct execution of a flight. For example, a checker
     118 * may check if the \ref mlx.checks.StrobeLightsChecker
     119 * "strobe lights" are switched on and off at the right stages of the
     120 * flight. But some checkers simply log some \ref
     121 * mlx.checks.AltimeterLogger "value" whenever it changes
     122 * in an "interesting" way, or \ref mlx.checks.ACARSSender "send the
     123 * ACARS" periodically.
     124 *
     125 * There is also a \ref mlx.checks.StageCheker "checker" which
     126 * detects the changes in the stage of the flight, and calls the
     127 * \ref mlx.acft.Aircraft.setStage "setStage" function of the
     128 * aircraft, if there is a change. It first calls the 
     129 * \ref mlx.flight.Flight "flight"'s \ref mlx.flight.Flight.setStage
     130 * "setStage" function, which notifies the GUI and the \ref
     131 * mlx.logger.Logger "logger" of this change, and records the block
     132 * and flight times. Then the aircraft's \c setStage function logs
     133 * some values in case of certain stages, such as the takeoff weights
     134 * and speeds when the takeoff stage is entered. After calling the
     135 * checkers, the \c handleState function of the aircraft calls the
     136 * \ref mlx.flight.Flight.handleState "function" with the same name of
     137 * the flight. It again records some statistical data, such as the
     138 * flown distance and the amount of fuel used, and calls the \ref
     139 * mlx.soundsched.SoundScheduler "sound scheduler" to check if some
     140 * backround sound should be played. If the check list hotkey is
     141 * pressed, the \ref mlx.soundsched.ChecklistScheduler
     142 * "checklist scheduler" is notified too.
     143 *
     144 * As mentioned, there is a \ref mlx.logger.Logger "logger" in the
     145 * application, which contains the textual log lines as well as the
     146 * faults and their scores.
     147 *
     148 * The business logic part contains many other components, but they
     149 * are quite simple and are built around the principles mentioned
     150 * above. Consult the documentation and the code of the relevant
     151 * modules for more information.
     152 *
     153 * \subsection arch_gui GUI     
     154 *
     155 * As mentioned, the GUI is implemented using Gtk+. This toolkit
     156 * provides the Glade graphical user interface designer, but due to
     157 * the requirement of supporting both Gtk+ 2 and 3, and due to a so-so
     158 * experience with Glade in an earlier project, it was decided to not
     159 * use it. Instead, the GUI elements are created and handled by
     160 * hand-written code.
     161 *
     162 * The central class of the graphical user interface is
     163 * mlx.gui.gui.GUI. Upon creation, it creates the rest of the GUI,
     164 * sets up the menus and shortcuts, etc. It also maintains the
     165 * connection to the simulator and creates the \ref mlx.flight.Flight
     166 * "flight" and \ref mlx.flight.Aircraft "aircraft" objects as
     167 * needed.
     168 *
     169 * To understand the operation of the GUI, one should be familiar with
     170 * Gtk+, but otherwise it is pretty straighforward. See the
     171 * documentation of the relevant modules for more information.
    52172 */
    53173 
  • src/mlx/gui/common.py

    r300 r302  
    1818# Windows or when the \c FORCE_PYGTK environment variable is set.
    1919#
    20 # Besides this there some common utility classes and functions.
     20# Besides this there are some common utility classes and functions.
    2121
    2222#-----------------------------------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.