Creating guided tours

From OpenRocket wiki
Jump to: navigation, search

Guided tours are interactive help systems within OpenRocket. They are defined as a set of "slides", where each slide has an image (typically a screenshot) and a short amount of descriptive text. The description text can be HTML-formatted, and can also contain links to other tours.


Common files[edit]

Two common files are used in the tour loading:

datafiles/tours/tours.txt contains a list of all tour files, one per line. There are relative to the tours directory, for example "introduction/introduction.tour". Blank lines and comment lines are ignored.

datafiles/tours/style.css is a common CSS style file for all tours. This provides additional formatting for the HTML, though the formatting should be kept at a minimum.

The tours themselves are read for the files specified in the tours.txt file.


Tour files[edit]

Typically a tour will have a directory of its own, containing the tour definition files and related images.

The tour definition file is a text file in UTF-8 encoding with the following format:

#
# Any lines starting with a hash are comments.
#

# First non-blank, non-comment line in the file is the title - this cannot contain HTML
A sample tour

# The lines before the first slide are the tour description
<p>This is the tour description.
<p>It can contain multiple paragraphs using a simple HTML syntax.


# Slides are started by containing an image name withing brackets
[slide1.png]
<p>The description for the slide follows.  It can contain HTML marking such as <b>bold</b>, <i>italics</i>, <sub>subscripts</sub> or <sup>superscripts</sup>.
<p>Each paragraph within the slide should be started with an HTML paragraph element.

# Next slide, please
[slide2.jpg]
<p>Slide images can be either PNG or JPG.
<p>Slides <a href="another_tour">can even contain links</a> to other tours.

The images are read from the same directory as the tour definition file.


Localization[edit]

Tours can be localized by creating a translated version of the tour definition file. If the base definition file is "example.tour", the German translation would be put in "example_de.tour".

If localized screenshots are needed, the screenshots should be put into the tour directory, and the localized tour definition needs to point to those image files. (The localized image files are not loaded automatically - the tour definition must explicitly point to them.)

For clarity, the localized screenshots should still be named as the base file with the appropriate language code appended (e.g. main_window.png -> main_window_de.png).


Image management[edit]

The screenshots often need to be resized suitably to the dialog size, and also to reduce their size. In some cases modifications are made to the screenshots to highlight some details (example).

To preserve the original image and to make it easier to make updates later on, the source image can be saved to resources-src/, and automatically converted into the proper size for the slides. The script resources-src/datafiles/tours/convert-images.sh performs the conversion automatically (but must be run separately). It can convert PNG and JPEG images (named *.png and *.jpg) and Gimp layered image files (named *.xcf.gz).

For example, the image at resources-src/tours/introduction/main_window_top.xcf.gz is automatically converted into resources/datafiles/tours/introduction/main_window_top.jpg.

Images that originally are 50kB or less and have no significant modifications should be saved directly into resources/ to preserve the image quality.


Testing the tours[edit]

The easiest way to test tours during development is to fetch the code from SVN using Eclipse, add the tour files to the appropriate place and either run OpenRocket from Eclipse or by using the run.sh script. Then select Help → Guided Tours. Remember to add the new tour definition file to tours.txt!

OpenRocket needs to be restarted every time changes are made to the tour files.


Example tour files[edit]

The tour definition file for the OpenRocket introduction is in SVN: resources/datafiles/tours/introduction/introduction.tour

The full directory with the images is: resources/datafiles/tours/introduction/

The list of all tours is: resources/datafiles/tours/tours.txt


Tour ideas[edit]

Some ideas for guided tours:

  • Introduction (DONE)
  • Creating a simple rocket design (In Progress)
  • Defining motors (In Progress)
  • Simulating a flight (In Progress)
  • Plotting options (In Progress)
  • Rocket display options
  • Rocket design analysis
  • Automatic optimization
  • Creating a multi-stage design
  • Creating a clustered design