FFGo -- A powerful graphical launcher for FlightGear

-------------------------------------------------------------------------------

This software is a fork of the excellent FGo![1] program written by
Robert 'erobo' Leda, see HISTORY below for details.

  [1] https://sites.google.com/site/erobosprojects/flightgear/add-ons/fgo


Contents

  Note For FGo! Users
  Configuration
  Main Menu Items
  Command Line Options Window
  Command Window
  Output Window
  Tips & Tricks
  Known Bugs And Limitations
  History


-------------------------------------------------------------------------------

NOTE FOR FGo! USERS

Except in rather unlikely cases[1], a configuration file (normally
~/.fgo/config) written by FGo! 1.5.5 or earlier should be usable as is
by FFGo, except that FFGo expects its configuration file in
~/.ffgo/config (%APPDATA%/FFGo/config on Windows). If FFGo finds a
~/.fgo/config file on startup but no ~/.ffgo/config, it will offer you
to copy the former to the latter, effectively basing your new FFGo
configuration on your existing FGo! configuration.

  [1] Such as having things like '\#' or '\[' in your Command Line
      Options window; or lines beginning with '['; or '{' at the very
      beginning of the text contained in this window.

FFGo offers advanced possibilities based on variables and boolean
expressions to describe the argument list to pass to FlightGear. You can
read about them in docs/README.conditional-config.

-------------------------------------------------------------------------------

CONFIGURATION

In order to use FFGo, you need to first set it up. Open the preferences
window (in menu choose: Settings => Preferences) and fill in the empty
entry fields. Filling the first three entries in the “FlightGear
settings” tab is necessary for proper operation of the program---the
rest is optional.

Tip: Hover the mouse pointer over any option to see its description.

Note: if you have installed GeographicLib's MagneticField program and it
is not in your PATH, you can indicate its location in the
“Miscellaneous” tab of the Preferences dialog.

Changes in the “FlightGear settings” and “Statistics” tabs are
immediately applied after clicking on the “Save Settings” button,
however changes in the “Miscellaneous” tab may require restarting FFGo
for them to be applied. Most notably, changing the interface language or
font size requires restarting FFGo to be fully effective---as far as the
chosen translation is complete, of course.

-------------------------------------------------------------------------------

MAIN MENU ITEMS

File:

    Load...     -- load the specified config file

    Reload config file -- reload FFGo's configuration file (~/.ffgo/config
                   on Unix-like systems, %APPDATA%/FFGo/config on Windows)

    Save as...  -- save settings to the specified config file

    Run FlightGear -- self-explanatory; same effect as the “Run FG” button

    Save & Quit -- save settings and quit the application

    Quit        -- quit the application

Settings:

    Show installed airports only -- only airports present in scenery
                   actually installed on the hard drive will be shown in the
                   airport list.

    Update list of installed airports -- scan hard drive for installed
                   scenery and update the airport list. It works only if
                   “Show installed airports only” is selected.

    ========================== Four check buttons ==========================

    Show FlightGear arguments -- show or hide the Command Window (see below)

    Show FlightGear arguments in separate window -- detach from, or reattach
                   to the main window, the Command Window

    Show FlightGear output -- show or hide the window gathering FlightGear's
                   output on stdout and stderr (“Output Window”, see below)

    Show FlightGear output in separate window -- detach from, or reattach to
                   the main window, the Output Window

    ========================================================================

    Preferences -- open the preferences window

Tools:

    Airport Finder -- open a dialog allowing to easily find airports
                   using various criteria: distance to a chosen,
                   “reference airport”; number of land runways, water
                   runways, or helipads; length of the longest or
                   shortest runway in the airport, etc. Results are
                   listed in a table giving these criteria for each
                   airport as well as the initial and final bearings for
                   the shortest path from or to the reference airport.
                   The table of results can be sorted according to
                   airport ICAO code, name or any of the aforementioned
                   criteria.

    GPS Tool    -- similar in some ways to the Airport Finder dialog,
                   but more convenient for the cases where you already
                   know the start and destination airports you are
                   interested in, and you just want to get the results
                   for these airports. Or you want to find the distance
                   and bearings for several particular pairs of
                   airports. This dialog also allows you to see the
                   flight duration for a given ground speed, and vice
                   versa.

    METAR       -- show METAR report for the selected airport, or the
                   nearest airport providing METAR data. These reports
                   are downloaded from <http://weather.noaa.gov/>.

    Pressure converter
                -- convert a pressure between inches of mercury (inHg)
                   and hectopascals (hPa). This can be useful to set the
                   altimeter when the QNH value obtained from METAR, for
                   instance, is not expressed in a unit that is directly
                   usable with your aircraft's instruments.

    Copy FG shell-equivalent command -- copy a shell command to the
                   clipboard that should be equivalent to the FlightGear
                   invocation FFGo would do if you were to click on the
                   “Run FG” button.

Help:

    Help        -- open the “Help” window

    Show available fgfs options
                -- display the output of 'fgfs --help --verbose' in a
                   dedicated window; this is useful to see which fgfs
                   options are available for use in the Options Window
                   (actually, --fg-root=... is also passed in the above
                   command in order to avoid a possible unwanted
                   FlightGear popup dialog, but this is an
                   implementation detail).

    About       -- open the “About” window

-------------------------------------------------------------------------------

COMMAND LINE OPTIONS WINDOW

In the text window at the left of the main window, right below the fgfs
status indicator[1], you can write any arguments for FlightGear
(“command line options”) that will be passed to 'fgfs', the FlightGear
executable. You should write each argument on a line of its own. Blank
lines are ignored, comments are started with '#', cf.
docs/README.conditional-config for details.

  [1] Which is green and reads “Ready” when FlightGear is not running.

Few options are provided by default, for more examples consult the
FlightGear documentation or check the Wiki at:

  http://wiki.flightgear.org/index.php/Command_Line_Options

The complete list of options understood by your FlightGear version can
be obtained using “Help → Show available fgfs options” in FFGo or,
equivalently, by running “fgfs --help --verbose” from a terminal.

FFGo offers advanced possibilities based on variables and boolean
expressions to describe the argument list to pass to FlightGear. You can
read about them in docs/README.conditional-config.

-------------------------------------------------------------------------------

COMMAND WINDOW

This window, normally located at the bottom of the FFGo main window,
indicates in real time which exact arguments will be passed to 'fgfs' if
the “Run FG” button is pressed (i.e., after evaluation of the conditions
allowed by CondConfigParser, that you may have included in the Command
Line Options window). The contents of this window is updated every time
you change the aircraft, airport, parking position, etc. as well as
after every change in the Command Line Options window.

The Command Window can be detached from the main window, reattached to
it or completely hidden. This can be done from the Settings menu. The
current setting, as well as the geometry of the window if it is
detached, are saved when choosing “Save & Quit”.

-------------------------------------------------------------------------------

OUTPUT WINDOW

The main text box in this window contains FlightGear's output on stdout
and stderr. It is updated in real time and can be useful to file bug
reports to FlightGear.

The “Save Log” button allows one to save the entire output of the last
FlightGear run to a file of your choice.

The “Open Log Directory” button is just a shortcut to open the default
log directory in a file manager. On systems different from Windows and
MacOS X, this is done with the 'xdg-open' program to allow you to
configure the file manager of your choice. On Windows and MacOS X, the
directory is opened using the standard mechanism.

The Output Window can be detached from the main window, reattached to it
or completely hidden. This can be done from the Settings menu. The
current setting, as well as the geometry of the window if it is
detached, are saved when choosing “Save & Quit”.

-------------------------------------------------------------------------------

TIPS & TRICKS

* If the airport data source is set to “Scenery” (now the default), then
  information about airports parking positions won't be available until
  the corresponding scenery is installed (except for the fallback method
  using FlightGear's apt.dat files).

  In such a case, if you use TerraSync, just run FlightGear once at the
  airport you want; this will automatically download the scenery for
  this airport. And make sure your TerraSync directory is listed (maybe
  along with others) in FFGo's FG_SCENERY setting in the Preferences
  dialog.

* For serious editing of the configuration, the builtin text widget in
  the FFGo interface may not be as convenient as a real text editor
  (Emacs, Vim, etc.). But you can perfectly use your favorite text
  editor on the configuration file (~/.ffgo/config on Unix-like systems,
  %APPDATA%/FFGo/config on Windows)! The only thing to remember in this
  case is to choose “Reload config file” (Ctrl-R) in FFGo before doing
  any other action (such as “Run FG” or “Save & Quit”) that saves the
  in-memory configuration to the config file. Otherwise, you may lose
  the changes to the config file made in-between outside FFGo.

* You can start a flight from an aircraft carrier. In the middle panel
  click on the current airport ICAO code (right under the aircraft
  picture) and choose one from the available ships. The ICAO code will
  then change to the selected ship's name, and will be highlighted in
  blue to indicate that you're now in “carrier mode”. The corresponding
  scenario will be automatically selected. To be able to choose airports
  again, you need to click on the carrier name, and from the pop-up list
  select “None”.

* In the “Select Scenario” list, you can right click on any scenario to
  see its description (if available).

* Window dimensions are saved when the “Save & Quit” button is clicked.

  More precisely, for the Command Window and Output Window, the whole
  geometry is always saved, i.e.: the size and offsets from the screen
  borders of each of these windows. For the main window, you can choose
  in the Preferences dialog (“Remember the main window position”)
  whether you want only the size to be saved, or the whole geometry. The
  first option corresponds to the behavior of FGo! 1.5.5, maybe it is
  suitable for tiling window managers? The second option is the default
  setting in FFGo.

-------------------------------------------------------------------------------

KNOWN BUGS AND LIMITATIONS

* Very long names for parking positions don't fit in the parking button.
  Just click on the button that makes the parking popup menu appear to
  see the full name of such parking positions.

-------------------------------------------------------------------------------

HISTORY

This software is a fork of the FGo![1] program written by Robert 'erobo'
Leda <erobo@wp.pl>. The original intent was not to fork but to improve
FGo!, however enough time has passed with interesting new features
working and no public release that I (Florent Rougon) finally decided to
publish the improved version so as to allow other people to benefit from
this work. After sending many patches written for FGo!, I changed the
name of the program to FFGo in order to avoid spreading confusion among
users, and released the code.

  [1] https://sites.google.com/site/erobosprojects/flightgear/add-ons/fgo

At the origin of this work, there is Robert's port of FGo! 1.5.5 to
Python 3. I had proposed to do it in 2014 as a base for my project of
conditional configuration parsing for FGo!, but Robert was kind enough
to do all the porting himself and send it to me by private email. This
allowed me to integrate my developments, starting with the addition of
CondConfigParser support. I set up a private Git repository to ease
collaboration with Robert, developed new features in it, integrated
Robert's proof of concept for the Command and Output windows, improved
upon it, etc. and now, this repository is public and used for FFGo
development.

-------------------------------------------------------------------------------


Thank you for using this software,
Florent Rougon <f.rougon@free.fr>

And thank you so much to my parents, who have provided such a fantastic
help to allow me to do this work despite the health problems.


(original text by FGo!'s author, Robert 'erobo' Leda)

Local Variables:
coding: utf-8
fill-column: 72
End:
