Changeset 300:f101bd18f39d

Timestamp:

07/22/12 17:28:25 (12 years ago)

Author:

István Váradi <ivaradi@…>

Branch:

default

Phase:

public

Message:

Added the module comments for the GUI

Location:

src/mlx/gui

Files:

• callouts.py (modified) (2 diffs)
• checklist.py (modified) (2 diffs)
• common.py (modified) (2 diffs)
• flight.py (modified) (2 diffs)
• gates.py (modified) (2 diffs)
• gui.py (modified) (2 diffs)
• info.py (modified) (2 diffs)
• monitor.py (modified) (2 diffs)
• pirep.py (modified) (2 diffs)
• prefs.py (modified) (2 diffs)
• statusbar.py (modified) (2 diffs)
• statusicon.py (modified) (2 diffs)
• update.py (modified) (2 diffs)
• weighthelp.py (modified) (2 diffs)

src/mlx/gui/callouts.py

@@ -1 @@
-# Module for editing checklists
-
-#------------------------------------------------------------------------------
 
 from common import *
@@ -11 +8 @@
 import os
 import re
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.callouts
+#
+# Editor dialog for approach callouts.
+#
+# The dialog consists of an aircraft type selector box at the top, and a table
+# with two buttons below it. The table contains the callout files with the
+# corresponding altitudes, and is sorted according to the altitude. When a new
+# file is added, the program finds out a new altitude for it. If the file's
+# name contains numbers that are not used as altitudes yet, the most suitable
+# of those numbers will be used. Otherwise a 'usual' altitude is searched for,
+# in the direction according to the sort order, and if that fails too, the
+# altitudes are tried one-by-one. See the
+# \ref ApproachCalloutsEditor._getNewAltitude function for more details.
 
 #------------------------------------------------------------------------------

src/mlx/gui/checklist.py

@@ -1 @@
-# Module for editing checklists
-
-#------------------------------------------------------------------------------
 
 from common import *
@@ -10 +7 @@
 
 import os
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.checklist
+#
+# The checklist editor dialog.
+#
+# This module implements the checklist editor dialog. A checklist is a list of
+# sound files that are played one-by-one when requested by the user. The top
+# part of the dialog contains an aircraft type selector. Below it, on the left
+# there is a file selector, and the list of the files in the checklist to the
+# right. There are some buttons in the middle to manipulate the checklist.
 
 #------------------------------------------------------------------------------

src/mlx/gui/common.py

@@ -1 @@
-# Common things for the GUI
 
 import mlx.const as _const
@@ -5 +4 @@
 
 import os
+
+#-----------------------------------------------------------------------------
+
+## @package mlx.gui.common
+#
+# Common definitions and utilities for the GUI
+#
+# The main purpose of this module is to provide common definitions for things
+# that are named differently in Gtk+ 2 and 3. This way the other parts of the
+# GUI have to check the version in use very rarely. The variable \ref pygobject
+# tells which version is being used. If it is \c True, Gtk+ 3 is used via the
+# PyGObject interface. Otherwise Gtk+ 2 is used, which is the default on
+# Windows or when the \c FORCE_PYGTK environment variable is set.
+#
+# Besides this there some common utility classes and functions.
+
+#-----------------------------------------------------------------------------
 
 appIndicator = False

src/mlx/gui/flight.py

@@ -1 @@
-# The flight handling "wizard"
 
 from mlx.gui.common import *
@@ -15 +14 @@
 import datetime
 import time
+
+#-----------------------------------------------------------------------------
+
+## @package mlx.gui.flight
+#
+# The flight "wizard".
+#
+# This module implements the main tab of the application, the flight
+# wizard. The wizard consists of \ref Page "pages", that come one after the
+# other. As some pages might be skipped, the pages dynamically store the index
+# of the previous page so that going back to it is simpler. The \ref
+# Page.activate "activate" function is called before a page is first shown
+# during a flight. This function should initialize the page's controls and fill
+# it with initial data. When a page is left for the first time, its \ref
+# Page.finalize "finalize" function is called. It should set those controls
+# insensitive, that will not be available if the user comes back to this page.
+#
+# Each page has a title at the top displayed in inverted colors and a big
+# font. There is a help text below it centered, that shortly describes what is
+# expected on the page. There can be two help texts: one shown when the page is
+# first displayed during a flight, another shown when the user goes back to the
+# page. The main content area is below this, also centered. Finally, there are
+# some buttons at the bottom on the right. As some buttons occur very
+# frequently, there are functions to add them (\ref Page.addCancelFlightButton
+# "addCancelFlightButton", \ref Page.addPreviousButton "addPreviousButton" and
+# \ref Page.addNextButton "addNextButton".
+#
+# The \ref Wizard class is the main class to collect the pages. It also stores
+# some data passed from one page to another and provides properties to access
+# data items set via the wizard pages.
 
 #-----------------------------------------------------------------------------

src/mlx/gui/gates.py

@@ -1 @@
-# Module to display the status of the planes and the gates
-
-#----------------------------------------------------------------------------
 
 from mlx.gui.common import *
@@ -7 +4 @@
 from mlx.i18n import xstr
 import mlx.const as const
+
+#-------------------------------------------------------------------------------
+
+## @package mlx.gui.gates
+#
+# The gate status display.
+#
+# This module contains the \ref FleetGateStatus widget, which is the tab
+# displaying the status of the MAVA Fleet and the gates at LHBP. The left side
+# of the widget is the table with the list of the planes and their states. The
+# right side displays the numbers of the gates and their occupation status.
 
 #-------------------------------------------------------------------------------

src/mlx/gui/gui.py

@@ -1 @@
-# The main file for the GUI
 # -*- coding: utf-8 -*-
 
@@ -32 +31 @@
 import datetime
 import webbrowser
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.gui
+#
+# The main GUI class.
+#
+# The \ref GUI class is the main class of the GUI. It is a connection listener,
+# and aggregates all the windows, the menu, etc. It maintains the connection to
+# the simulator as well as the flight object.
 
 #------------------------------------------------------------------------------

src/mlx/gui/info.py

@@ -1 @@
-#The Flight Info tab
 
 from common import *
@@ -5 +4 @@
 from mlx.i18n import xstr
 import mlx.const as const
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.info
+#
+# The flight info tab.
+#
+# This module implements to \ref FlightInfo class, which is the widget for the
+# extra information related to the flight. It contains text areas for the
+# comments and the flight defects at the top next to each other, and the frame
+# for the delay codes at the bottom in the centre.
 
 #------------------------------------------------------------------------------

src/mlx/gui/monitor.py

@@ -1 @@
-# The monitoring window
 
 from mlx.gui.common import *
@@ -7 +6 @@
 
 import time
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.monitor
+#
+# The monitoring window
+#
+# The \ref MonitorWindow class is a window containing the data received from
+# the simulator by the logger.
 
 #------------------------------------------------------------------------------

src/mlx/gui/pirep.py

@@ -1 @@
-# Module for the detailed PIREP viewer
-
-#------------------------------------------------------------------------------
 
 from common import *
@@ -9 +6 @@
 
 import time
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.pirep
+#
+# The detailed PIREP viewer.
+#
+# The \ref PIREPViewer class is a dialog displaying all information found in a
+# PIREP. It consists of three tabs. The Data tab displays the simple,
+# itemizable data. The Comments & defects tab contains the flight comments and
+# defects, while the Log tab contains the flight log collected by the
+# \ref mlx.logger.Logger "logger".
 
 #------------------------------------------------------------------------------

src/mlx/gui/prefs.py

@@ -1 @@
-# Module for the preferences dialog
-
-#------------------------------------------------------------------------------
 
 from common import *
@@ -10 +7 @@
 
 import urlparse
+
+#------------------------------------------------------------------------------
+
+## @package mlx.gui.prefs
+#
+# The preferences dialog.
+#
+# This module implements the preferences dialog, allowing the editing of the
+# configuration of the program. The preferences are grouped into tabs, each
+# containing the necessary controls to set the various options.
 
 #------------------------------------------------------------------------------

src/mlx/gui/statusbar.py

@@ -1 @@
-# Implementation of the status bar.
-
-#-------------------------------------------------------------------------------
 
 from common import *
@@ -10 +7 @@
 import math
 import time
+
+#-------------------------------------------------------------------------------
+
+## @package mlx.gui.statusbar
+#
+# The status bar.
+#
+# This module implements the status bar seen at the lower part of the main
+# window. It contains the icon depicting the status of the connection to the
+# simulator, the current flight stage, rating and the simulator time.
 
 #-------------------------------------------------------------------------------

src/mlx/gui/statusicon.py

@@ -1 @@
-# Implementation of the status icon
-
-#-------------------------------------------------------------------------------
 
 from common import *
@@ -7 +4 @@
 import mlx.const as const
 from mlx.i18n import xstr
+
+#-------------------------------------------------------------------------------
+
+## @package mlx.gui.statusicon
+#
+# The status icon.
+#
+# This module implements that status icon displayed on the Windows or the GNOME
+# taskbar, or whatever the place for status icons is called in the used
+# environment. It works with both the more modern appindicator interface
+# (mainly found on Ubuntu), if that is available, or with the older status icon
+# support in Gtk (which is used on Windows as well). In this latter case, the
+# icon has a tooltip with the flight stage and rating information, while these
+# data are placed into the menu in case of appindicator.
 
 #-------------------------------------------------------------------------------

src/mlx/gui/update.py

@@ -1 @@
-# The GUI part of the update
-
-#-------------------------------------------------------------------------------
 
 from mlx.gui.common import *
@@ -13 +10 @@
 import os
 import sys
+
+#-------------------------------------------------------------------------------
+
+## @package mlx.gui.update
+#
+# The GUI part of the update.
+#
+# This module implements the GUI portion of the \ref mlx.update
+# "automatic update" function. The update runs in a separate thread, which puts
+# the relevant events into the Gtk event loop.
 
 #-------------------------------------------------------------------------------

src/mlx/gui/weighthelp.py

@@ -1 @@
-# The weight calculation help window
-
-#-------------------------------------------------------------------------------
 
 from mlx.gui.common import *
@@ -7 +4 @@
 from mlx.i18n import xstr
 from mlx.checks import PayloadChecker
+
+#-------------------------------------------------------------------------------
+
+## @package mlx.gui.weighthelp
+#
+# The weight calculation help tab.
+#
+# This module implements the tab containing the weight calculation help. 
 
 #-------------------------------------------------------------------------------