FlightGear wiki - User contributions [en]

Canvas event handling

2018-02-15T23:13:02Z

TheTom: Add keyboard events

{{infobox subsystem
|name = Canvas Event Handling
|started = 11/2012 (Available since [[Changelog 2.10|FlightGear 2.10]])
|description = DOM like event handling
|developers = {{usr|TheTom}}
|folders =
* {{flightgear file|src/Canvas/gui_mgr.hxx}}
* {{simgear file|simgear/canvas}}
}}
{{Template:Canvas Navigation}}

The Canvas event handling system closely follows the W3C [http://www.w3.org/TR/DOM-Level-3-Events/ DOM Event Model]. If you have already used events in JavaScript and HTML most concepts of the Canvas event system should be already familiar to you. The most notable difference is the missing capture phase, but it is usually not used anyhow.

Listeners - simple Nasal functions - can be attached to every element inside the Canvas and the Canvas itself. Once a certain action - like moving the mouse or pressing a button - occurs the associated listeners are called. We can use this for example to detect whether the mouse has moved over an element or if a certain element has been clicked. For this you should understand how [[Using_Nasal_functions#Function_closures|closures work]].

= Listen for events =

To receive events callback function can be added to elements on a Canvas as well as to the Canvas itself:

<syntaxhighlight lang="nasal">
canvas.addEventListener("<type>", <func>);
canvas_element.addEventListener("<type>", <func>);
</syntaxhighlight>

For each placement of a Canvas handling events can be enabled or disabled. A Canvas placed in a PUI (old GUI) widget or as standalone GUI window receives events by default, whereas Canvases placed onto the aircraft model or in the scenery do not receive any events by default.

{{Note|When using the old [[Howto:Adding_a_canvas_to_a_GUI_dialog|PUI/XML GUI]] with a '''<nowiki><canvas></nowiki>'''-widget placement, PUI does not trigger any mouseover/hover (mousemove) events. Mouse clicks/wheel/drag are working as expected. For all other placements like on standalone Canvas windows and [[Howto:Add_a_2D_canvas_instrument_to_your_aircraft|3D models]] there is no such limitation. If you find that your code doesn't work as expected, make sure to verify that your layers (canvas groups) use matching z-index ordering, or overlapping symbols may prevent event handlers from being triggered/called.}}

For standalone GUI windows setting '''capture-events''' to ''0'' or ''1'' enables or disables handling of events respectively. For a Canvas placed onto a 3d model, setting ''capture-events'' inside the placement can be used to activate event handling:

<syntaxhighlight lang="nasal">
var dlg = canvas.Window.new([152,74]);

# Disable event handling for this window. Events will pass through
# and can reach any window or also object covered by the window.
dlg.setBool("capture-events", 0);

# Place the canvas onto the PFD and enable receiving events
my_canvas.addPlacement({"node": "PFD-Screen", "capture-events": 1});
</syntaxhighlight>

= Event flow =

Events always are targeted at a specific element inside the Canvas. Before any event handler is called the propagation path for the event is determined. It consists of the event target itself and all its ancestor elements (Groups) up to and including the Canvas. Afterwards - during the ''Target Phase'' - all listeners registered on the event target are called. Finally - during the ''Bubbling Phase'' - the event bubbles up the tree, following the propagation path determined in the first step, and all listeners attached to the according elements are called.

[[File:Canvas Eventflow.png|thumb|540px|center|Event flow of Canvas Events similar to W3C DOM Event flow <ref name="dom-event-flow">DOM Level 3 event flow. http://www.w3.org/TR/DOM-Level-3-Events/#event-flow</ref>.]]

= Event classes =

<syntaxhighlight lang="nasal">
var Event = {
# Name of event type [read-only]
type: <typename>,

# Target element [read-only]
target: <target-element>,

# Element the currently called listener is attached to [read-only]
currentTarget: <target-element>,

# Stop further propagation of event (stop
# bubbling up to its parents)
stopPropagation: func()
};

# Since FG 3.1.0
var DeviceEvent = {
parents: [Event],

# State of all keyboard modifiers at the time the event has
# been triggered [read-only]
modifiers: <modifier-mask>,

# [read-only]
ctrlKey: <was-ctrl-down>,

# [read-only]
shiftKey: <was-shift-down>,

# [read-only]
altKey: <was-alt-down>,

# [read-only]
metaKey: <was-meta-down>
}

# Since FG 3.1.0
var KeyboardEvent = {
parents: [DeviceEvent],

# [read-only]
key: <key-string>,

# Location of the key on the keyboard [read-only]
#
# https://www.w3.org/TR/DOM-Level-3-Events/#events-keyboard-key-location
#
# 0 standard location
# 1 left
# 2 right
# 3 numpad
location: <key-location>,

# [read-only]
repeat: <is-repeat>,

# [read-only]
charCode: <code>,

# [read-only]
keyCode: <code>
}

var MouseEvent = {
# [FG >= 3.1.0]
parents: [DeviceEvent],

# [FG < 3.1.0]
parents: [Event],

# Position in screen coordinates [read-only]
screenX: <screen-x>,
screenY: <screen-y>,

# Position in window/canvas coordinates [read-only]
clientX: <client-x>,
clientY: <client-y>,

# Position in local/element coordinates [read-only]
localX: <local-x>,
localY: <local-y>,

# Distance to position of previous event [read-only]
deltaX: <delta-x>,
deltaY: <delta-y>,

# Current click count (number of clicks within a certain
# time limit. max. 3) [read-only]
click_count: <click-count>,

# Button which triggered this event [read-only, FG >= 3.1.0]
#
# 0: primary button (usually the left button)
# 1: auxiliary button (usually the middle button/mouse wheel)
# 2: secondary button (usually the right button)
button: <button>,

# State of all mouse buttons at the time the event has been
# triggered [read-only, FG >= 3.1.0]
buttons: <active-button-mask>
};
</syntaxhighlight>

== Middle-mouse button emulation ==

2-button mice can be setup to emulate a middle-mouse button click by pressing the left and right button simultaneously. On Ubuntu you can use [https://apps.ubuntu.com/cat/applications/gpointing-device-settings gpointing-device-settings] to enable "middle button emulation"
<ref>https://wiki.ubuntu.com/X/Quirks#A2-button_Mice</ref>
<ref>http://askubuntu.com/questions/140828/how-can-i-paste-text-by-pressing-the-left-and-right-mouse-buttons-at-the-same-ti</ref>.

= Event types =
{| class="wikitable"
|-
! Type !! Description !! DOM equivalent event !! Bubbles <ref name="dom-event-flow"/>
|-
| ''mousedown'' || Mouse button pressed || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mousedown mousedown] || {{tick}}
|-
| ''mouseup'' || Mouse button released || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseup mouseup] || {{tick}}
|-
| ''click'' || ''mousedown'' + ''mouseup'' have been triggered for this element without moving more than a certain maximum distance || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-click click] || {{tick}}
|-
| ''dblclick'' || Two ''click'' events have been triggered for this element without moving more than a certain maximum distance and time limit || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-dblclick dblclick] || {{tick}}
|-
| ''drag'' || The mouse has been moved with a button down. After dragging has started above an element, all consecutive ''drag'' events are sent to this element even if the mouse leaves its area || || {{tick}}
|-
| ''wheel'' || Mouse wheel rotated (see deltaY for direction) || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-wheel wheel] || {{tick}}
|-
| ''mousemove'' || Mouse has moved while beeing inside the area of the target element. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mousemove mousemove] || {{tick}}
|-
| ''mouseover'' || Mouse has entered a child or the element itself. ''mouseover'' is also triggered if the mouse moves from one child element to another. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseover mouseover] || {{tick}}
|-
| ''mouseout'' || Mouse has left a child or the element itself. ''mouseout'' is also triggered if the mouse moves from one child element to another. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseout mouseout] || {{tick}}
|-
| ''mouseenter'' || Mouse has entered a child or the element itself. In contrary to ''mouseover'', ''mouseenter'' is not triggered if the mouse moves from one child element to another, but only the first time the element or one of its children is entered. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseenter mouseenter] || {{cross}}
|-
| ''mouseleave'' || Mouse has left the element and all of its children. In contrary to ''mouseout'', ''mouseleave'' is not triggered if the mouse moves from one child element to another, but only if the mouse moves outside the element and all its children. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseleave mouseleave] || {{cross}}
|-
| ''keydown'' || A key was pressed down. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-keydown keydown] || {{tick}}
|-
| ''keyup'' || A key was released. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-keyup keyup] || {{tick}}
|-
| ''keypress'' || A key creating a printable character was pressed. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-keypress keypress] || {{tick}}
|}

= Example Code =
(Note that this example makes use of advanced Nasal concepts, such as anonymous functions, method chaining and lots of embedded/inline code):
<syntaxhighlight lang="nasal">
# Canvas GUI demo
#
# Shows an icon in the top-right corner which upon click opens a simple window
#

var dlg = canvas.Window.new([32,32]);
dlg.setInt("tf/t[1]", 4)
.setInt("right", 4);
var my_canvas = dlg.createCanvas()
.set("background", "rgba(0,0,0,0)");
var root = my_canvas.createGroup();
canvas.parsesvg(root, "gui/dialogs/images/icon-aircraft.svg");

my_canvas.addEventListener("click", func
{
var dlg = canvas.Window.new([400,300], "dialog");
var my_canvas = dlg.createCanvas()
.set("background", "#f2f1f0");
var root = my_canvas.createGroup();
root.addEventListener("click", func(e) {
printf( "click: screen(%.1f|%.1f) client(%.1f|%.1f) click count = %d",
e.screenX, e.screenY,
e.clientX, e.clientY,
e.click_count );
});
root.addEventListener("dblclick", func(e) {
printf( "dblclick: screen(%.1f|%.1f) client(%.1f|%.1f)",
e.screenX, e.screenY,
e.clientX, e.clientY );
});
root.addEventListener("wheel", func(e) {
printf( "wheel: screen(%.1f|%.1f) client(%.1f|%.1f) delta = %.1f",
e.screenX, e.screenY,
e.clientX, e.clientY,
e.deltaY );
});
var text =
root.createChild("text")
.setText( "This could be used for building an 'Aircraft Help' dialog.\n"
~ "You can also #use it to play around with the new Canvas system :). β" )
.setTranslation(10, 30)
.set("alignment", "left-top")
.set("character-size", 14)
.set("font", "LiberationFonts/LiberationSans-Regular.ttf")
.set("max-width", 380)
.set("fill", "black");
var text_move =
root.createChild("text")
.setText("Mouse moved over text...")
.setTranslation(20, 200)
.set("alignment", "left-center")
.set("character-size", 15)
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")
.set("fill", "#ff0000")
.hide();
var visible_count = 0;
text.addEventListener("mouseover", func text_move.show());
text.addEventListener("mouseout", func text_move.hide());
});
</syntaxhighlight>

<references/>

[[Category:Canvas GUI]]

Template:Canvas Navigation

2018-02-15T22:25:04Z

TheTom:

<noinclude>{{Informative template|1=
== Usage ==
Add the template to the top of the article text.
{{obr}}'''Canvas Navigation'''{{cbr}}

Adding the template to an page in the main namespace, the article namespace, or the howto namespace will add [[:Category:Canvas]] to the page. In addition [[:Category:Howto]] will be added to articles in the howto namespace, and [[:Category:Core development projects]] will be added to articles in the main namespace.

}}

[[Category:Navigation templates]]
[[Category:Canvas]]
</noinclude>{{forum|71|Canvas}}
{{sidebar with collapsible headers
| name = Canvas Navigation
| title = Canvas - the FlightGear 2D drawing API
| contentstyle = text-align: left;
| state = collapsed

| content1 =
* [[Canvas]] - Main Page
* [[Canvas News]] - for the latest developments
* [[Canvas Efforts]] - projects using the Canvas system
* [[Canvas FAQs]] - frequently asked questions
* [[Canvas - Getting started]]

* [[Canvas Development]] (core)
* [[Canvas Troubleshooting]] (core)
* [[Canvas Sandbox]] (core)
* [[Canvas Scenery Overlays]] (RFC)
* [[Howto:Processing legacy PUI dialogs using Canvas|PUI2Canvas]] (PUI/XML Parser)
* [[Canvas GUI]]
* [[Canvas Widgets]]
* [[Canvas Maps]]
* [[Canvas Snippets]]

| heading2 = Frameworks
| content2 =
{{Canvas Frameworks|mode=navbar}}
* [[Canvas Glass Cockpit Efforts]]

| heading3 = Tutorials
| content3 =
* [[Howto:Getting started with Canvas]]
* [[Howto: Canvas Troubleshooting]]
* [[Howto:Adding a canvas to a GUI dialog]] (PUI!)
* [[Howto:Creating a Canvas GUI dialog file]] (New)
* [[Howto:Dynamic Liveries via Canvas]] (new)
* [[Howto:Creating a Canvas GUI Widget]]
* [[Howto:Add a 2D canvas instrument to your aircraft]]
* [[Howto:Parsing 2D Instruments using the Canvas]]
* [[Howto:Creating fullscreen Canvas applications]]
* [[Howto:Use SVG inside a Canvas]]
* [[Howto:Extend the Canvas SVG module]]
* [[Howto:Serializing a Canvas to SVG]]
* [[Howto:Canvas applications as Nasal submodules]]
* [[Howto:Using raster images and nested canvases]]

* [[Howto:Creating a Canvas graph widget]]
* [[Canvas HUD]]
| heading4 = Reference
| content4 =
* [[Canvas Element]]
** [[Canvas Group|Group]]
** [[Canvas Image|Image]]
** [[Canvas Map|Map]]
** [[Canvas Path|Path]]
** [[Canvas Text|Text]]
* [[Canvas Nasal API]]
** [[Canvas MessageBox|MessageBox]]
** [[Canvas Layout System|Layout System]]
* [[Canvas GUI API]]
* [[Canvas Event Handling|Event Handling]]
| heading5 = Related
| content5 =
* [[Canvas Properties]]
* [[Unifying the 2D rendering backend via canvas]]
* [[Howto:Create a 2D drawing API for FlightGear]]
* [[Howto:Use a Camera View in an Instrument]]
* [[Howto:Extending Canvas to support rendering 3D models]]

| heading6 = To be ported
| content6 =
* [[Navigation display]] {{Progressbar|70}}
* [[Map]] {{Progressbar|80}}
* [[FGCanvas]] {{Progressbar|20}}
* [[Canvas Nasal/JavaScript Subset]]

| heading7 = Deprecated by Canvas
| content7 =
* [[Complex Glass Cockpit Avionics]]

}}<includeonly>{{main other|[[Category:Canvas]][[Category:Core development projects]]}}
{{howto other|[[Category:Canvas]][[Category:Howto]]}}</includeonly>

Canvas Image

2018-02-01T07:45:39Z

TheTom: Fix url

[[Category:Canvas Elements]]
{{Template:Canvas Navigation}}

= Properties =

Additionally to the properties supported by every [[Canvas Element]], Canvas Images support the following properties:

== src ==

* '''Version''': FlightGear >= 3.1
* '''Format''': [<protocol>://]<path> (Supported protocols: canvas://, <nowiki>http://</nowiki>)

<syntaxhighlight lang="nasal">
# Use file inside default search paths
img.set("src", "gui/dialogs/images/exit.png");

# Show canvas with index 3
img.set("src", "canvas://by-index/texture[3]");

# Download and show FlightGear logo
img.set("src", "http://wiki.flightgear.org/skins/common/images/icons-fg-135.png");

# Show canvas available as object
img.set("src", my_canvas.getPath());
</syntaxhighlight>

== x/y ==
== size ==

== fill ==

* '''Format''': <color> (#rrggbb, rbg(r,g,b), rgba(r,g,b,a) [r,g,b -> 0-255; a -> 0.0-1.0])
* '''Default''': #ffffff (white)

Image background color. Each pixel is modulated with the background color. If the image shall be displayed unchanged use white as background color.

<syntaxhighlight lang="nasal">
# White with alpha of 0.5 (=half transparent)
img.set("fill", "rgba(255,255,255,0.5)");

# red completely opaque
img.set("fill", "#ff0000");
</syntaxhighlight>

== slice ==

* '''Format''': [<number>%?]{1,4} fill?
* '''Default''': (empty) (disabled)

Image slicing (or scale-9, 9-slice) is a technique for dividing an image into nine regions. While scaling such an image the four corner regions will be shown undistorted, whereas the other regions are scaled to fit into the remaining parts. See the CSS3 [https://www.w3.org/TR/css-backgrounds-3/#the-border-image-slice border-image-slice] property for more information.

<syntaxhighlight lang="nasal">
# Top/bottom offset 10%, left/right offset 5%, fill center
img.set("slice", "10% 5% fill");

# All offsets 8 pixels, only draw border and do not fill center
img.set("slice", "8");

# Disable slicing
img.set("slice", "");
</syntaxhighlight>

== outset ==

* '''Format''': [<number>%?]{1,4}
* '''Default''': (empty) (disabled)

Let the image extend outside its specified size. The areas extending outside the original dimensions are just drawn but not included in the bounding box, and therefore ignored for event handling and distance/margin calculations. This could be used, for example, to draw a shadow around an element which is ignored for handling events.

<syntaxhighlight lang="nasal">
# Top outset 10%, left/right outset 5%, bottom outset 10 pixels
img.set("outset", "10% 5% 10");

# All offsets 8 pixels
img.set("outset", "8");

# Disable outset
img.set("outset", "");
</syntaxhighlight>

== file (deprecated) ==

* '''Version''': FlightGear <= 3.0

Same as ''src''. Use ''src'' with FlightGear >= 3.1.

Canvas Path

2018-01-29T18:24:48Z

TheTom: New and missing properties.

[[Category:Canvas Elements]]
{{Template:Canvas Navigation}}

= Properties =

Additionally to the properties supported by every [[Canvas Element]], Canvas Paths support the following properties:

== fill ==

* '''Format''': "none" | <color> (#rrggbb, rbg(r,g,b), rgba(r,g,b,a) [r,g,b -> 0-255; a -> 0.0-1.0])
* '''Default''': "none" (do not fill path)

Color to fill the path.

== fill-opacity ==

* '''Format''': <number> (any real number between 0.0 and 1.0)
* '''Default''': 1.0 (not transparent)

Factor to multiply the alpha channel of the ''fill'' color.

== fill-rule ==

* '''Format''': "pseudo-nonzero" | "evenodd"
* '''Default''': "evenodd"

== stroke ==

* '''Format''': "none" | <color> (#rrggbb, rbg(r,g,b), rgba(r,g,b,a) [r,g,b -> 0-255; a -> 0.0-1.0])
* '''Default''': "none" (do not draw path)

Color to draw the path.

== stroke-opacity ==

* '''Format''': <number> (any real number between 0.0 and 1.0)
* '''Default''': 1.0 (not transparent)

Factor to multiply the alpha channel of the ''stroke'' color.

== stroke-width ==

* '''Format''': <number> (any real number)
* '''Default''': 1.0

Specify the width (in pixels) of the stroke used to draw the path.

<syntaxhighlight lang="nasal">
# 5 pixel wide, red stroke
path.set("stroke", "red")
.set("stroke-width", 5);
</syntaxhighlight>

== stroke-dasharray ==

Line stipple (see [http://www.w3.org/TR/SVG/painting.html#StrokeDasharrayProperty SVG stroke-dasharray])

== stroke-linecap ==

* '''Format''': "round" | "square" | "butt"
* '''Default''': "butt"

Line end (see [http://www.w3.org/TR/SVG/painting.html#StrokeLinecapProperty SVG stroke-linecap])

== stroke-linejoin ==

* '''Format''': "round" | "bevel" | "miter"
* '''Default''': "miter"

Line corner (see [http://www.w3.org/TR/SVG/painting.html#StrokeLinejoinProperty SVG stroke-linejoin])

Canvas snippets

2015-04-30T14:24:21Z

TheTom: /* A simple tile map */ Tilesize

{{Stub}}
{{-}}
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.

Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.

We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.

Contributions added to this article should ideally satisfy some requirements:
* be entirely self-contained
* contain good/clear comments
* have pointers/references to related code/use-cases
* make assumptions explicit
* contain screen shots for each example
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables

{{Canvas Navigation}}

== Creating a standalone Canvas ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[Special:UploadWizard|Upload requested]] ||

<syntaxhighlight lang="nasal" enclose="div">
var (width, height) = (512,512);
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc)
var myCanvas = canvas.new({
"name": "Livery Test", # The name is optional but allow for easier identification
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]
# which will be stretched the size of the texture, required)
"mipmapping": 1 # Enable mipmapping (optional)
});

# set background color
myCanvas.set("background", canvas.style.getColor("bg_color"));

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!
var window = canvas.Window.new([width,height],"dialog");
window.setCanvas(myCanvas);
</syntaxhighlight>

|}

== Creating Tooltips ==
== Creating Popups ==
== Creating a Canvas GUI Window ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}

{{Canvas Snippets Boilerplate}}

|}

== Adding Raster Images ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||
<syntaxhighlight lang="nasal" enclose="div">

# path is relative to $FG_ROOT (base package)
var path = "Textures/Splash1.png";
# create an image child for the texture
var child = root.createChild("image")
.setFile(path)
.setTranslation(100, 10)
.setSize(130, 130);
</syntaxhighlight>

|}

== Adding Raster Images downloaded on demand ==

The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is":
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||
<syntaxhighlight lang="nasal" enclose="div">

# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)
var window = canvas.Window.new([400,200],"dialog");

# adding a canvas to the new window and setting up background colors/transparency
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));

# Using specific css colors would also be possible:
# myCanvas.set("background", "#ffaac0");

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

# path now a URL
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";

# create an image child for the texture
var child=root.createChild("image")
.setFile( url )
.setTranslation(45,22) # centered, in relation to dialog coordinates
.setSize(310,155); # image dimensions
</syntaxhighlight>

|}

== Adding OpenVG Paths ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}

<syntaxhighlight lang="nasal" enclose="div">
var graph = root.createChild("group");

var x_axis = graph.createChild("path", "x-axis")
.moveTo(10, height/2)
.lineTo(width-10, height/2)
.setColor(1,0,0)
.setStrokeLineWidth(3);

var y_axis = graph.createChild("path", "y-axis")
.moveTo(10, 10)
.lineTo(10, height-10)
.setColor(0,0,1)
.setStrokeLineWidth(2);
</syntaxhighlight>
|-
|}

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]]
| {{Note|This assumes that you are appending this to the snippet shown above.}}

<syntaxhighlight lang="nasal" enclose="div">

var points = [ 60,height-20,
230,height-100,
];

var track = graph.createChild("path", "track")
.moveTo(10, height/2)
.quadTo( points )
.setColor(0,1,0)
.setStrokeLineWidth(4);

</syntaxhighlight>
|-
|}

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]]
| {{Note|This assumes that you are appending this to the snippet shown above.}}

<syntaxhighlight lang="nasal" enclose="div">
var points = [ 60,height-20,
120,height-120,
230,height-100,
];

var track = graph.createChild("path", "track")
.moveTo(10, height/2)
.cubicTo( points )
.setColor(0,1,0)
.setStrokeLineWidth(4);

</syntaxhighlight>
|-
|}

== Adding Vector Images ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# change the background color
myCanvas.set("background", "#ffaac0");

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";
var svg_symbol = root.createChild('group');
canvas.parsesvg(svg_symbol, filename);

svg_symbol.setTranslation(width/2,height/2);

#svg_symbol.setScale(0.2);
#svg_symbol.setRotation(radians)
</syntaxhighlight>
|-
|}

== Using the SymbolCache ==
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one).

Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]
...
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]]
| {{Caution|This is currently untested code}}
<syntaxhighlight lang="nasal" enclose="div">

##
# this is the function that draws a symbol using OpenVG paths
# it accepts a group to draw to and returns the rendered group
# to the caller
var drawVOR = func(group) {
return group.createChild("path")
.moveTo(-15,0)
.lineTo(-7.5,12.5)
.lineTo(7.5,12.5)
.lineTo(15,0)
.lineTo(7.5,-12.5)
.lineTo(-7.5,-12.5)
.close()
.setStrokeLineWidth(line_width) # style-able
.setColor(color); # style-able
};

var style = { # styling related attributes (as per the draw* function above)
line_width: 3,
scale_factor: 1,
color: [1,0,0],
};

# create a new cache entry for the styled symbol
var myCachedSymbol = canvas.StyleableCacheable.new(
name:'myVOR', draw_func: drawVOR,
cache: canvas.SymbolCache32x32, # the cache to be used
draw_mode: canvas.SymbolCache.DRAW_CENTERED,
relevant_keys: ['line_width', 'color'], # styling related attributes
);

var target = root.createChild('group');

var x=0;
var y=height/2;

var xoffset=50;

# render 5 instances symbols using the style specified above
for (var i=0;i<5;i+=1) {
# look up the raster image for the symbol
# render it using the passed style and adjust scaling
var instanced = myCachedSymbol.render(target, style)
.setScale(style.scale_factor)
.setTranslation(x+=xoffset,y);
}</syntaxhighlight>
|-
|}

The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this:
<syntaxhighlight lang="nasal">
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);
</syntaxhighlight>

== Adding Text Elements ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}
<syntaxhighlight lang="nasal" enclose="div">
var myText = root.createChild("text")
.setText("Hello world!")
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio
.setColor(1,0,0,1) # red, fully opaque
.setAlignment("center-center") # how the text is aligned to where you place it
.setTranslation(160, 80); # where to place the text
</syntaxhighlight>
|-
|}

== Adding GUI Labels ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead
label.setText("Hello World!");
myLayout.addItem(label);

var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead
label2.setText("Hello FlightGear");
myLayout.addItem(label2);
</syntaxhighlight>

|}

== Adding GUI Buttons (Layouts)==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]]
|

{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

# click button

var button = canvas.gui.widgets.Button.new(root, canvas.style, {})
.setText("Click on me")
.setFixedSize(75, 25);

button.listen("clicked", func {
# add code here to react on click on button.
print("Button clicked !");
});

myLayout.addItem(button);
</syntaxhighlight>

|-
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]
| <syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

var button = canvas.gui.widgets.Button.new(root, canvas.style, {})
.setText("Toggle me")
.setCheckable(1) # this indicates that is should be a toggle button
.setChecked(0) # depressed by default
.setFixedSize(75, 25);

button.listen("toggled", func (e) {
if( e.detail.checked ) {
# add code here to react on button being depressed.
} else {
# add code here to react on button not being depressed.
}
});

myLayout.addItem(button);

</syntaxhighlight>

|}

== Canvas Input Dialog ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]
||
<syntaxhighlight lang="nasal" enclose="div">
# create a new InputDialog with a title, label, and a callback
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {
if (value) gui.popupTip("You entered: "~value);
});
</syntaxhighlight>

|}

== Using Layouts ==

== Using Styling ==
== Adding a HUD ==
== Adding a 2D Instrument ==
== Adding a 2D Panel ==
== Adding a PFD ==

== Adding a Failure Mgmt Widget ==
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}

== Adding a MapStructure map to a Canvas ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">

var TestMap = root.createChild("map");
TestMap.setController("Aircraft position");
TestMap.setRange(25);

TestMap.setTranslation( myCanvas.get("view[0]")/2,
myCanvas.get("view[1]")/2
);
var r = func(name,vis=1,zindex=nil) return caller(0)[0];

foreach(var type; [r('APT'), r('VOR') ] )
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);
</syntaxhighlight>

|}

== Customizing MapStructure Styling ==
{{WIP}}
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">
</syntaxhighlight>

|}

== Using MapStructure and Overlays ==
{{FGCquote
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Fri Apr 10</nowiki>
}}
}}
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">

</syntaxhighlight>
|}

== A simple tile map ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]
|
<syntaxhighlight lang="nasal" enclose="div">
var (width,height) = (768,512);
var tile_size = 256;

var window = canvas.Window.new([width, height],"dialog")
.set('title', "Tile map demo");
var g = window.getCanvas(1)
.createGroup();

# Simple user interface (Buttons for zoom and label for displaying it)
var zoom = 10;
var type = "map";

var ui_root = window.getCanvas().createGroup();
var vbox = canvas.VBoxLayout.new();
window.setLayout(vbox);

var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})
.setText("+")
.listen("clicked", func changeZoom(1));
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})
.setText("-")
.listen("clicked", func changeZoom(-1));
button_in.setSizeHint([32, 32]);
button_out.setSizeHint([32, 32]);

var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});

var button_box = canvas.HBoxLayout.new();
button_box.addItem(button_in);
button_box.addItem(label_zoom);
button_box.addItem(button_out);
button_box.addStretch(1);

vbox.addItem(button_box);
vbox.addStretch(1);

var changeZoom = func(d)
{
zoom = math.max(2, math.min(19, zoom + d));
label_zoom.setText("Zoom " ~ zoom);
updateTiles();
}

# http://polymaps.org/docs/
# https://github.com/simplegeo/polymaps
# https://github.com/Leaflet/Leaflet

var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';

# http://otile1.mqcdn.com/tiles/1.0.0/map
# http://otile1.mqcdn.com/tiles/1.0.0/sat
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)
var makeUrl =
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');
var makePath =
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');
var num_tiles = [4, 3];

var center_tile_offset = [
(num_tiles[0] - 1) / 2,
(num_tiles[1] - 1) / 2
];

# simple aircraft icon at current position/center of the map
g.createChild("path")
.moveTo( tile_size * center_tile_offset[0] - 10,
tile_size * center_tile_offset[1] )
.horiz(20)
.move(-10,-10)
.vert(20)
.set("stroke", "red")
.set("stroke-width", 2)
.set("z-index", 1);

##
# initialize the map by setting up
# a grid of raster images

var tiles = setsize([], num_tiles[0]);
for(var x = 0; x < num_tiles[0]; x += 1)
{
tiles[x] = setsize([], num_tiles[1]);
for(var y = 0; y < num_tiles[1]; y += 1)
tiles[x][y] = g.createChild("image", "map-tile");
}

var last_tile = [-1,-1];
var last_type = type;

##
# this is the callback that will be regularly called by the timer
# to update the map
var updateTiles = func()
{
# get current position
var lat = getprop('/position/latitude-deg');
var lon = getprop('/position/longitude-deg');

var n = math.pow(2, zoom);
var offset = [
n * ((lon + 180) / 360) - center_tile_offset[0],
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]
];
var tile_index = [int(offset[0]), int(offset[1])];

var ox = tile_index[0] - offset[0];
var oy = tile_index[1] - offset[1];

for(var x = 0; x < num_tiles[0]; x += 1)
for(var y = 0; y < num_tiles[1]; y += 1)
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));

if( tile_index[0] != last_tile[0]
or tile_index[1] != last_tile[1]
or type != last_type )
{
for(var x = 0; x < num_tiles[0]; x += 1)
for(var y = 0; y < num_tiles[1]; y += 1)
{
var pos = {
z: zoom,
x: int(offset[0] + x),
y: int(offset[1] + y),
type: type
};

(func {
var img_path = makePath(pos);
var tile = tiles[x][y];

if( io.stat(img_path) == nil )
{ # image not found, save in $FG_HOME
var img_url = makeUrl(pos);
print('requesting ' ~ img_url);
http.save(img_url, img_path)
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));
}
else # cached image found, reusing
{
print('loading ' ~ img_path);
tile.set("src", img_path)
}
})();
}

last_tile = tile_index;
last_type = type;
}
};

##
# set up a timer that will invoke updateTiles at 2-second intervals
var update_timer = maketimer(2, updateTiles);
# actually start the timer
update_timer.start();

##
# set up default zoom level
changeZoom(0);
</syntaxhighlight>
|}

== Adding a NavDisplay ==

== Adding a CDU ==

== Adding a Multi-Function Display (MFD) ==

Canvas snippets

2015-04-29T14:32:14Z

TheTom: Tile map demo

{{Stub}}
{{-}}
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.

Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.

We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.

Contributions added to this article should ideally satisfy some requirements:
* be entirely self-contained
* contain good/clear comments
* have pointers/references to related code/use-cases
* make assumptions explicit
* contain screen shots for each example
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables

{{Canvas Navigation}}

== Creating a standalone Canvas ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[Special:UploadWizard|Upload requested]] ||

<syntaxhighlight lang="nasal" enclose="div">
var (width, height) = (512,512);
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc)
var myCanvas = canvas.new({
"name": "Livery Test", # The name is optional but allow for easier identification
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]
# which will be stretched the size of the texture, required)
"mipmapping": 1 # Enable mipmapping (optional)
});

# set background color
myCanvas.set("background", canvas.style.getColor("bg_color"));

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!
var window = canvas.Window.new([width,height],"dialog");
window.setCanvas(myCanvas);
</syntaxhighlight>

|}

== Creating Tooltips ==
== Creating Popups ==
== Creating a Canvas GUI Window ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}

{{Canvas Snippets Boilerplate}}

|}

== Adding Raster Images ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||
<syntaxhighlight lang="nasal" enclose="div">

# path is relative to $FG_ROOT (base package)
var path = "Textures/Splash1.png";
# create an image child for the texture
var child = root.createChild("image")
.setFile(path)
.setTranslation(100, 10)
.setSize(130, 130);
</syntaxhighlight>

|}

== Adding Raster Images downloaded on demand ==

The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is":
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||
<syntaxhighlight lang="nasal" enclose="div">

# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)
var window = canvas.Window.new([400,200],"dialog");

# adding a canvas to the new window and setting up background colors/transparency
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));

# Using specific css colors would also be possible:
# myCanvas.set("background", "#ffaac0");

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

# path now a URL
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";

# create an image child for the texture
var child=root.createChild("image")
.setFile( url )
.setTranslation(45,22) # centered, in relation to dialog coordinates
.setSize(310,155); # image dimensions
</syntaxhighlight>

|}

== Adding OpenVG Paths ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}

<syntaxhighlight lang="nasal" enclose="div">
var graph = root.createChild("group");

var x_axis = graph.createChild("path", "x-axis")
.moveTo(10, height/2)
.lineTo(width-10, height/2)
.setColor(1,0,0)
.setStrokeLineWidth(3);

var y_axis = graph.createChild("path", "y-axis")
.moveTo(10, 10)
.lineTo(10, height-10)
.setColor(0,0,1)
.setStrokeLineWidth(2);
</syntaxhighlight>
|-
|}

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]]
| {{Note|This assumes that you are appending this to the snippet shown above.}}

<syntaxhighlight lang="nasal" enclose="div">

var points = [ 60,height-20,
230,height-100,
];

var track = graph.createChild("path", "track")
.moveTo(10, height/2)
.quadTo( points )
.setColor(0,1,0)
.setStrokeLineWidth(4);

</syntaxhighlight>
|-
|}

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]]
| {{Note|This assumes that you are appending this to the snippet shown above.}}

<syntaxhighlight lang="nasal" enclose="div">
var points = [ 60,height-20,
120,height-120,
230,height-100,
];

var track = graph.createChild("path", "track")
.moveTo(10, height/2)
.cubicTo( points )
.setColor(0,1,0)
.setStrokeLineWidth(4);

</syntaxhighlight>
|-
|}

== Adding Vector Images ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# change the background color
myCanvas.set("background", "#ffaac0");

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";
var svg_symbol = root.createChild('group');
canvas.parsesvg(svg_symbol, filename);

svg_symbol.setTranslation(width/2,height/2);

#svg_symbol.setScale(0.2);
#svg_symbol.setRotation(radians)
</syntaxhighlight>
|-
|}

== Using the SymbolCache ==
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one).

Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]
...
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]]
| {{Caution|This is currently untested code}}
<syntaxhighlight lang="nasal" enclose="div">

##
# this is the function that draws a symbol using OpenVG paths
# it accepts a group to draw to and returns the rendered group
# to the caller
var drawVOR = func(group) {
return group.createChild("path")
.moveTo(-15,0)
.lineTo(-7.5,12.5)
.lineTo(7.5,12.5)
.lineTo(15,0)
.lineTo(7.5,-12.5)
.lineTo(-7.5,-12.5)
.close()
.setStrokeLineWidth(line_width) # style-able
.setColor(color); # style-able
};

var style = { # styling related attributes (as per the draw* function above)
line_width: 3,
scale_factor: 1,
color: [1,0,0],
};

# create a new cache entry for the styled symbol
var myCachedSymbol = canvas.StyleableCacheable.new(
name:'myVOR', draw_func: drawVOR,
cache: canvas.SymbolCache32x32, # the cache to be used
draw_mode: canvas.SymbolCache.DRAW_CENTERED,
relevant_keys: ['line_width', 'color'], # styling related attributes
);

var target = root.createChild('group');

var x=0;
var y=height/2;

var xoffset=50;

# render 5 instances symbols using the style specified above
for (var i=0;i<5;i+=1) {
# look up the raster image for the symbol
# render it using the passed style and adjust scaling
var instanced = myCachedSymbol.render(target, style)
.setScale(style.scale_factor)
.setTranslation(x+=xoffset,y);
}</syntaxhighlight>
|-
|}

The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this:
<syntaxhighlight lang="nasal">
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);
</syntaxhighlight>

== Adding Text Elements ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}
<syntaxhighlight lang="nasal" enclose="div">
var myText = root.createChild("text")
.setText("Hello world!")
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio
.setColor(1,0,0,1) # red, fully opaque
.setAlignment("center-center") # how the text is aligned to where you place it
.setTranslation(160, 80); # where to place the text
</syntaxhighlight>
|-
|}

== Adding GUI Labels ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead
label.setText("Hello World!");
myLayout.addItem(label);

var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead
label2.setText("Hello FlightGear");
myLayout.addItem(label2);
</syntaxhighlight>

|}

== Adding GUI Buttons (Layouts)==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]]
|

{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

# click button

var button = canvas.gui.widgets.Button.new(root, canvas.style, {})
.setText("Click on me")
.setFixedSize(75, 25);

button.listen("clicked", func {
# add code here to react on click on button.
print("Button clicked !");
});

myLayout.addItem(button);
</syntaxhighlight>

|-
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]
| <syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

var button = canvas.gui.widgets.Button.new(root, canvas.style, {})
.setText("Toggle me")
.setCheckable(1) # this indicates that is should be a toggle button
.setChecked(0) # depressed by default
.setFixedSize(75, 25);

button.listen("toggled", func (e) {
if( e.detail.checked ) {
# add code here to react on button being depressed.
} else {
# add code here to react on button not being depressed.
}
});

myLayout.addItem(button);

</syntaxhighlight>

|}

== Canvas Input Dialog ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]
||
<syntaxhighlight lang="nasal" enclose="div">
# create a new InputDialog with a title, label, and a callback
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {
if (value) gui.popupTip("You entered: "~value);
});
</syntaxhighlight>

|}

== Using Layouts ==

== Using Styling ==
== Adding a HUD ==
== Adding a 2D Instrument ==
== Adding a 2D Panel ==
== Adding a PFD ==

== Adding a Failure Mgmt Widget ==
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}

== Adding a MapStructure map to a Canvas ==
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">

var TestMap = root.createChild("map");
TestMap.setController("Aircraft position");
TestMap.setRange(25);

TestMap.setTranslation( myCanvas.get("view[0]")/2,
myCanvas.get("view[1]")/2
);
var r = func(name,vis=1,zindex=nil) return caller(0)[0];

foreach(var type; [r('APT'), r('VOR') ] )
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);
</syntaxhighlight>

|}

== Customizing MapStructure Styling ==
{{WIP}}
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">
</syntaxhighlight>

|}

== Using MapStructure and Overlays ==
{{FGCquote
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Fri Apr 10</nowiki>
}}
}}
{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">

</syntaxhighlight>
|}

== A simple tile map ==

{| class="wikitable"
|-
! Screenshot !! Code
|-
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]
|
<syntaxhighlight lang="nasal" enclose="div">
var window = canvas.Window.new([768, 512],"dialog")
.set('title', "Tile map demo");
var g = window.getCanvas(1)
.createGroup();

# Simple user interface (Buttons for zoom and label for displaying it)
var zoom = 10;
var type = "map";

var ui_root = window.getCanvas().createGroup();
var vbox = canvas.VBoxLayout.new();
window.setLayout(vbox);

var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})
.setText("+")
.listen("clicked", func changeZoom(1));
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})
.setText("-")
.listen("clicked", func changeZoom(-1));
button_in.setSizeHint([32, 32]);
button_out.setSizeHint([32, 32]);

var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});

var button_box = canvas.HBoxLayout.new();
button_box.addItem(button_in);
button_box.addItem(label_zoom);
button_box.addItem(button_out);
button_box.addStretch(1);

vbox.addItem(button_box);
vbox.addStretch(1);

var changeZoom = func(d)
{
zoom = math.max(2, math.min(19, zoom + d));
label_zoom.setText("Zoom " ~ zoom);
updateTiles();
}

# http://polymaps.org/docs/
# https://github.com/simplegeo/polymaps
# https://github.com/Leaflet/Leaflet

var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';

# http://otile1.mqcdn.com/tiles/1.0.0/map
# http://otile1.mqcdn.com/tiles/1.0.0/sat
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)
var makeUrl =
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');
var makePath =
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');
var num_tiles = [4, 3];

var center_tile_offset = [
(num_tiles[0] - 1) / 2,
(num_tiles[1] - 1) / 2
];

# simple aircraft icon at current position/center of the map
g.createChild("path")
.moveTo( 256 * center_tile_offset[0] - 10,
256 * center_tile_offset[1] )
.horiz(20)
.move(-10,-10)
.vert(20)
.set("stroke", "red")
.set("stroke-width", 2)
.set("z-index", 1);

var tiles = setsize([], num_tiles[0]);
for(var x = 0; x < num_tiles[0]; x += 1)
{
tiles[x] = setsize([], num_tiles[1]);
for(var y = 0; y < num_tiles[1]; y += 1)
tiles[x][y] = g.createChild("image", "map-tile");
}

var last_tile = [-1,-1];
var last_type = type;

var updateTiles = func()
{
var lat = getprop('/position/latitude-deg');
var lon = getprop('/position/longitude-deg');

var n = math.pow(2, zoom);
var offset = [
n * ((lon + 180) / 360) - center_tile_offset[0],
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]
];
var tile_index = [int(offset[0]), int(offset[1])];

var ox = tile_index[0] - offset[0];
var oy = tile_index[1] - offset[1];

for(var x = 0; x < num_tiles[0]; x += 1)
for(var y = 0; y < num_tiles[1]; y += 1)
tiles[x][y].setTranslation(int((ox + x) * 256 + 0.5), int((oy + y) * 256 + 0.5));

if( tile_index[0] != last_tile[0]
or tile_index[1] != last_tile[1]
or type != last_type )
{
for(var x = 0; x < num_tiles[0]; x += 1)
for(var y = 0; y < num_tiles[1]; y += 1)
{
var pos = {
z: zoom,
x: int(offset[0] + x),
y: int(offset[1] + y),
type: type
};

(func {
var img_path = makePath(pos);
var tile = tiles[x][y];

if( io.stat(img_path) == nil )
{
var img_url = makeUrl(pos);
print('requesting ' ~ img_url);
http.save(img_url, img_path)
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));
}
else
{
print('loading ' ~ img_path);
tile.set("src", img_path)
}
})();
}

last_tile = tile_index;
last_type = type;
}
};
var update_timer = maketimer(2, updateTiles);
update_timer.start();

changeZoom(0);
</syntaxhighlight>
|}

== Adding a NavDisplay ==

== Adding a CDU ==

== Adding a Multi-Function Display (MFD) ==

File:Canvas - Tile map demo.png

2015-04-29T14:28:11Z

TheTom: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=A simple, canvas based tile map which is centered around the aircraft.}}
|date=2015-04-29 16:26:33
|source={{own}}
|author=[[User:TheTom|TheTom]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-4.0}}

[[Category:Canvas]]

User:TheTom

2014-11-10T16:58:04Z

TheTom:

[[Category:FlightGear Core developers]]
[[Category:Developer Plans]]

{{User
|name = Thomas (TheTom)
|location = Austria}}

== Development plan ==

=== [[Canvas|Canvas (The FlightGear 2D rendering API)]] ===

* Canvas based GUI {{Pending}}
** Create [[Canvas MessageBox|dialogs]] {{Done}} and widgets {{Pending}} from Nasal
** Handle keyboard input {{Done}}
** Expose character and cursor positions (eg. for text input/editing) {{Pending}}
** Parse current gui and menu xml files {{Not done}}
* Canvas based HUD {{Pending}}
** Nasal API/framwork {{Pending}}
** Parse HUD xml files {{Not done}}
** Use Canvas GUI for 2D HUD {{Not done}}
** object placements for 3D HUD? {{Pending}}
*** Take care of projection/moving head {{Pending}}
* Canvas (API/General)
** Rotate map children according to map heading {{Pending}}

=== Animation ===

* Improved/advanced animations
** [[Tracking animation]] {{Done}}
* Blender animation/basic fdm exporter {{Pending}}

=== Simulation / systems ===

* Generic sytem building blocks {{Pending}}
** Allow to use conditions/expressions/property-rules/etc. to simulate any type of system (eg. electric, hydraulic,...) and especially take care to be able to build reusable building blocks.
** Unify/cleanup expression parser {{Not done}}
** Generic APU {{Pending}}
** Generic electrical system {{Pending}}
* Generic VDGS {{Pending}}
* MCDU/FMS/AMU framework {{Pending}}
* Blender system exporter {{Not done}}

=== Aircraft / Scenery ===

* [[Lockheed Martin C-130J Super Hercules]] {{Pending}}
* [http://www.flightgear.org/forums/viewtopic.php?f=5&t=18475 Flughafen Graz-Thalerhof (LOWG)] {{Pending}}

=== General ===

* Respect XDG directories (and environment variables) {{issue|1468}} {{Not done}}

Canvas Element

2014-11-10T16:49:34Z

TheTom: Some info on blend functions.

[[Category:Canvas Elements]]
{{Template:Canvas Navigation}}

A handful of rendering primitives are available to draw on a canvas. Properties (see [[Property Tree]] for general information on FlightGear's property system) are used to control the appearance and behaviour of such ''Element''s.

= Properties =

== blend-* ==

Set OpenGL blend function.
For a single function for all color channels (as with [https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml glBlendFunc]) use the properties '''"blend-source"''' and '''"blend-destination"'''.
To set separate blend functions for the rgb and alpha channels (as with [https://www.opengl.org/sdk/docs/man/html/glBlendFuncSeparate.xhtml glBlendFuncSeparate]) use the properties with '''"*-rgb"''' and '''"*-alpha"''' prefix.

* '''Format''': "dst-alpha" | "dst-color" | "one" | "one-minus-dst-alpha" | "one-minus-dst-color" | "one-minus-src-alpha" | "one-minus-src-color" | "src-alpha" | "src-alpha-saturate" | "src-color" | "constant-color" | "one-minus-constant-color" | "constant-alpha" | "one-minus-constant-alpha" | "zero" (See the [https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml#description OpenGL Reference Pages] for details)

Setting different blend functions for rgb and alpha:

<syntaxhighlight lang="nasal">
# Standard alpha blending
el.set("blend-source-rgb", "src-alpha");
el.set("blend-destination-rgb", "one-minus-src-alpha");

# Just keep current alpha
el.set("blend-source-alpha", "zero");
el.set("blend-destination-alpha", "one");
</syntaxhighlight>

== clip ==

* '''Format''': "auto" | "rect(<top>, <right>, <bottom>, <left>)"
* '''Default''': "auto"

Set clipping rectangle for element and all its children. Only what is inside the clipping bounds will be shown.

<syntaxhighlight lang="nasal">
# set clipping rectangle with x=10, y=5, width=90, height=45
el.set("clip", "rect(5, 100, 50, 10)");
</syntaxhighlight>

== clip-frame ==

* '''Format''': GLOBAL | PARENT | LOCAL
* '''Default''': GLOBAL

Set the coordinate reference frame for the ''clip'' property.

<syntaxhighlight lang="nasal">
# set clip reference frame to parent coordinate frame
el.set("clip-frame", canvas.Element.PARENT);
</syntaxhighlight>

== visible ==

== z-index ==

* '''Format''': <number> (Integer)
* '''Default''': 0

Change order in which elements are drawn. Elements with higher ''z-index'' are drawn later and cover allready drawn elements on overlapping parts.

<syntaxhighlight lang="nasal">
# Draw before all elements (if no z-index of the other elements is lower than zero)
el.set("z-index", -1);

# Ensure el2 is drawn before/below el1
el1.set("z-index", 51);
el2.set("z-index", 50);
</syntaxhighlight>

Canvas snippets

2014-09-22T09:06:50Z

TheTom: [canvas.]style is not a layout but the current global canvas gui style...

{{Stub}}
{{WIP}}

{{Canvas Navigation}}

== Creating a standalone Canvas ==

{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| please upload ...||

<syntaxhighlight lang="nasal" enclose="div">
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc)
var myCanvas = canvas.new({
"name": "Livery Test", # The name is optional but allow for easier identification
"size": [512, 512], # Size of the underlying texture (should be a power of 2, required) [Resolution]
"view": [512, 512], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]
# which will be stretched the size of the texture, required)
"mipmapping": 1 # Enable mipmapping (optional)
});

# set background color
myCanvas.set("background", canvas.style.getColor("bg_color"));

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!
var window = canvas.Window.new([512,512],"dialog");
window.setCanvas(myCanvas);
</syntaxhighlight>

|-
|}

== Creating Tooltips ==
== Creating Popups ==
== Creating a Canvas GUI Window ==

{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}

<syntaxhighlight lang="nasal" enclose="div">
# create a new window, dimensions are 320 x 160, using the dialog decoration (i.e. titlebar)
var window = canvas.Window.new([320,160],"dialog");

# adding a canvas to the new window and setting up background colors/transparency
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));

# Using specific css colors would also be possible:
# myCanvas.set("background", "#ffaac0");

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();
</syntaxhighlight>

|-
|}

== Adding Raster Images ==

{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||
<syntaxhighlight lang="nasal" enclose="div">

var filename = "Textures/Splash1.png";
# create an image child for the texture
var child=root.createChild("image")
.setFile( filename )
.setTranslation(100,10)
.setSize(130,130);
</syntaxhighlight>

|-
|}

== Adding OpenVG Paths ==
== Adding Vector Images ==
== Adding Text Elements ==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]||

|
{{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}
<syntaxhighlight lang="nasal" enclose="div">
var myText = root.createChild("text")
.setText("Hello world!")
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio
.setColor(1,0,0,1) # red, fully opaque
.setAlignment("center-center") # how the text is aligned to where you place it
.setTranslation(160, 80); # where to place the text
</syntaxhighlight>
|-
|}

== Adding GUI Labels ==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]||

|
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead
label.setText("Hello World!");
myLayout.addItem(label);

var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead
label2.setText("Hello FlightGear");
myLayout.addItem(label2);
</syntaxhighlight>
|-
|}

== Adding GUI Buttons (Layouts)==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]] ||

{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}
<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

# click button

var button = canvas.gui.widgets.Button.new(root, canvas.style, {})
.setText("Click on me")
.setFixedSize(75, 25);

button.listen("clicked", func {
# add code here to react on click on button.
print("Button clicked !");
});

myLayout.addItem(button);
</syntaxhighlight>

<syntaxhighlight lang="nasal" enclose="div">
# create a new layout
var myLayout = canvas.HBoxLayout.new();
# assign it to the Canvas
myCanvas.setLayout(myLayout);

var button = canvas.gui.widgets.Button.new(root, canvas.style, {})
.setText("Toggle me")
.setCheckable(1) # this indicates that is should be a toggle button
.setChecked(0) # depressed by default
.setFixedSize(75, 25);

button.listen("toggled", func (e) {
if( e.detail.checked ) {
# add code here to react on button being depressed.
} else {
# add code here to react on button not being depressed.
}
});

myLayout.addItem(button);

</syntaxhighlight>
|-
|}

== Canvas Input Dialog ==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]
||
<syntaxhighlight lang="nasal" enclose="div">
# create a new InputDialog with a title, label, and a callback
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {
if (value) gui.popupTip("You entered: "~value);
});
</syntaxhighlight>
|-
|}

== Using Layouts ==

== Using Styling ==
== Adding a HUD ==
== Adding a 2D Instrument ==
== Adding a 2D Panel ==
== Adding a PFD ==

== Using the SymbolCache ==

== Adding a MapStructure map to a Canvas ==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]
||
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">

var TestMap = root.createChild("map");
TestMap.setController("Aircraft position");
TestMap.setRange(25);

TestMap.setTranslation( myCanvas.get("view[0]")/2,
myCanvas.get("view[1]")/2
);
var r = func(name,vis=1,zindex=nil) return caller(0)[0];

foreach(var type; [r('APT'), r('VOR') ] )
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);
</syntaxhighlight>
|-
|}

== Adding a NavDisplay ==

== Adding a Multi-Function Display (MFD) ==

Canvas snippets

2014-09-15T13:50:27Z

TheTom: I prefer generic setters and colors from the theme.

{{Stub}}
{{WIP}}

{{Canvas Navigation}}

== Creating a Canvas GUI Window ==

{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}

<syntaxhighlight lang="nasal" enclose="div">
# create a new window, dimensions are 320 x 160, using the dialog decoration (i.e. titlebar)
var window = canvas.Window.new([320,160],"dialog");

# adding a canvas to the new window and setting up background colors/transparency
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));

# Using specific css colors would also be possible:
# myCanvas.set("background", "#ffaac0");

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();
</syntaxhighlight>

|-
|}

== Adding a MapStructure map to a Canvas ==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]
||
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}
<syntaxhighlight lang="nasal" enclose="div">

var TestMap = root.createChild("map");
TestMap.setController("Aircraft position");
TestMap.setRange(25);

TestMap.setTranslation( myCanvas.get("view[0]")/2,
myCanvas.get("view[1]")/2
);
var r = func(name,vis=1,zindex=nil) return caller(0)[0];

foreach(var type; [r('APT'), r('VOR') ] )
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);
</syntaxhighlight>
|-
|}

== Canvas Input Dialog ==
{| class="wikitable"
|-
! Screenshot !! Code !!
|-
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]
||
<syntaxhighlight lang="nasal" enclose="div">
# create a new InputDialog with a title, label, and a callback
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {
if (value) gui.popupTip("You entered: "~value);
});
</syntaxhighlight>
|-
|}

User talk:TheTom

2014-09-08T09:31:19Z

TheTom:

== Template:Note ==
[http://wiki.flightgear.org/index.php?title=Template:Note&diff=74755&oldid=73671 Well spotted]. I tried fix it in a similar way earlier but did not seem to succeed for some reason. Your edit seem to work in the intended way though.

I have now made the same changes to its sister templates {{tl|warning}}, {{tl|caution}} and {{tl|tip}}.

Thanks!

—[[User:Johan G|Johan G]] ([[User_talk:Johan_G|Talk]] | [[Special:Contributions/Johan_G|contribs]]) 09:52, 5 August 2014 (UTC)

== tracking animation article not really helpful==
Hello Tom,

I just wanted to try your tracking animation for a scissor animation on a nose gear.
I followed your article here in the wiki. It don't work.

Looking at your C-130J doesn't help - as the objects name are not the same like in the animation file.
I remember that another user in the forum noticed it. On the other side I see the animation working on your C-130J.
Would you please so kind fix the article as it seems that very something very important to know is missing.

Cheers!

--[[User:HHS|HHS]] ([[User talk:HHS|talk]]) 21:52, 3 September 2014 (UTC)

What does not work? Are there any error messages? I have just copied the XML from the C-130J without modifying it. Do you have an example which does not work?

--[[User:TheTom|TheTom]] ([[User talk:TheTom|talk]]) 09:31, 8 September 2014 (UTC)

User:TheTom

2014-08-20T09:04:34Z

TheTom:

[[Category:FlightGear Core developers]]
[[Category:Developer Plans]]

{{User
|name = Thomas (TheTom)
|location = Austria}}

== Development plan ==

=== GUI / render ===

* Canvas based GUI {{Pending}}
** Create dialogs {{Done}} and widgets {{Pending}} from Nasal
** Handle keyboard input {{Pending}}
** Expose character and cursor positions (eg. for text input/editing) {{Pending}}
** Parse current gui and menu xml files {{Not done}}
* Canvas based HUD {{Pending}}
** Nasal API/framwork {{Pending}}
** Parse HUD xml files {{Not done}}
** Use Canvas GUI for 2D HUD {{Not done}}
** object placements for 3D HUD? {{Pending}}
*** Take care of projection/moving head {{Pending}}
* Canvas (API/General)
** Rotate map children according to map heading {{Pending}}

=== Animation ===

* Improved/advanced animations
** [[Tracking animation]] {{Done}}
* Blender animation/basic fdm exporter {{Pending}}

=== Simulation / systems ===

* Generic sytem building blocks {{Pending}}
** Allow to use conditions/expressions/property-rules/etc. to simulate any type of system (eg. electric, hydraulic,...) and especially take care to be able to build reusable building blocks.
** Unify/cleanup expression parser {{Not done}}
** Generic APU {{Pending}}
** Generic electrical system {{Pending}}
* Generic VDGS {{Pending}}
* MCDU/FMS/AMU framework {{Pending}}
* Blender system exporter {{Not done}}

=== Aircraft / Scenery ===

* [[Lockheed Martin C-130J Super Hercules]] {{Pending}}
* [http://www.flightgear.org/forums/viewtopic.php?f=5&t=18475 Flughafen Graz-Thalerhof (LOWG)] {{Pending}}

=== General ===

* Respect XDG directories (and environment variables) {{issue|1468}} {{Not done}}

Canvas event handling

2014-08-05T09:42:59Z

TheTom: Example cleanup/formatting.

[[Category:Canvas]]
{{Template:Canvas Navigation}}

{{Note| This feature is only available in FlightGear versions >{{=}} 2.11 !
To really understand Canvas event handling, you should read [[Using listeners and signals with Nasal]] first and understand how [[Using_Nasal_functions#Function_closures|closures work]].}}

The Canvas event handling system closely follows the W3C [http://www.w3.org/TR/DOM-Level-3-Events/ DOM Event Model]. If you have already used events in JavaScript and HTML most concepts of the Canvas event system should be already familiar to you. The most notable difference is the missing capture phase, but it is usually not used anyhow.

Listeners - simple Nasal functions - can be attached to every element inside the Canvas and the Canvas itself. Once a certain action - like moving the mouse or pressing a button - occurs the associated listeners are called. We can use this for example to detect whether the mouse has moved over an element or if a certain element has been clicked.

= Listen for events =

To receive events callback function can be added to elements on a Canvas as well as to the Canvas itself:

<syntaxhighlight lang="nasal">
canvas.addEventListener("<type>", <func>);
canvas_element.addEventListener("<type>", <func>);
</syntaxhighlight>

For each placement of a Canvas handling events can be enabled or disabled. A Canvas placed in a PUI (old GUI) widget or as standalone GUI window receives events by default, whereas Canvases placed onto the aircraft model or in the scenery do not receive any events by default.

{{Note|When using the old [[Howto:Adding_a_canvas_to_a_GUI_dialog|PUI/XML GUI]] with a '''<nowiki><canvas></nowiki>'''-widget placement, PUI does not trigger any mouseover/hover (mousemove) events. Mouse clicks/wheel/drag are working as expected. For all other placements like on standalone Canvas windows and [[Howto:Add_a_2D_canvas_instrument_to_your_aircraft|3D models]] there is no such limitation. If you find that your code doesn't work as expected, make sure to verify that your layers (canvas groups) use matching z-index ordering, or overlapping symbols may prevent event handlers from being triggered/called.}}

For standalone GUI windows setting '''capture-events''' to ''0'' or ''1'' enables or disables handling of events respectively. For a Canvas placed onto a 3d model, setting ''capture-events'' inside the placement can be used to activate event handling:

<syntaxhighlight lang="nasal">
var dlg = canvas.Window.new([152,74]);

# Disable event handling for this window. Events will pass through
# and can reach any window or also object covered by the window.
dlg.setBool("capture-events", 0);

# Place the canvas onto the PFD and enable receiving events
my_canvas.addPlacement({"node": "PFD-Screen", "capture-events": 1});
</syntaxhighlight>

= Event flow =

Events always are targeted at a specific element inside the Canvas. Before any event handler is called the propagation path for the event is determined. It consists of the event target itself and all its ancestor elements (Groups) up to and including the Canvas. Afterwards - during the ''Target Phase'' - all listeners registered on the event target are called. Finally - during the ''Bubbling Phase'' - the event bubbles up the tree, following the propagation path determined in the first step, and all listeners attached to the according elements are called.

[[File:Canvas Eventflow.png|thumb|540px|center|Event flow of Canvas Events similar to W3C DOM Event flow <ref name="dom-event-flow">DOM Level 3 event flow. http://www.w3.org/TR/DOM-Level-3-Events/#event-flow</ref>.]]

= Event classes =

<syntaxhighlight lang="nasal">
var Event = {
# Name of event type [read-only]
type: <typename>,

# Target element [read-only]
target: <target-element>,

# Element the currently called listener is attached to [read-only]
currentTarget: <target-element>,

# Stop further propagation of event (stop
# bubbling up to its parents)
stopPropagation: func()
};

var MouseEvent = {
parents: [Event],

# Position in screen coordinates [read-only]
screenX: <screen-x>,
screenY: <screen-y>,

# Position in window/canvas coordinates [read-only]
clientX: <client-x>,
clientY: <client-y>,

# Position in local/element coordinates [read-only]
localX: <local-x>,
localY: <local-y>,

# Distance to position of previous event [read-only]
deltaX: <delta-x>,
deltaY: <delta-y>,

# Current click count (number of clicks within a certain
# time limit. max. 3) [read-only]
click_count: <click-count>,

# Buttons/modifiers require FlightGear >= 3.1.0

# Button which triggered this event [read-only]
#
# 0: primary button (usually the left button)
# 1: auxiliary button (usually the middle button/mouse wheel)
# 2: secondary button (usually the right button)
button: <button>,

# State of all mouse buttons at the time the event has been
# triggered [read-only]
buttons: <active-button-mask>,

# State of all keyboard modifiers at the time the event has
# been triggered [read-only]
modifiers: <modifier-mask>,

# [read-only]
ctrlKey: <was-ctrl-down>,

# [read-only]
shiftKey: <was-shift-down>,

# [read-only]
altKey: <was-alt-down>,

# [read-only]
metaKey: <was-meta-down>
};
</syntaxhighlight>

== Middle-mouse button emulation ==

2-button mice can be setup to emulate a middle-mouse button click by pressing the left and right button simultaneously. On Ubuntu you can use [https://apps.ubuntu.com/cat/applications/gpointing-device-settings gpointing-device-settings] to enable "middle button emulation"
<ref>https://wiki.ubuntu.com/X/Quirks#A2-button_Mice</ref>
<ref>http://askubuntu.com/questions/140828/how-can-i-paste-text-by-pressing-the-left-and-right-mouse-buttons-at-the-same-ti</ref>.

= Event types =
{| class="wikitable"
|-
! Type !! Description !! DOM equivalent event !! Bubbles <ref name="dom-event-flow"/>
|-
| ''mousedown'' || Mouse button pressed || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mousedown mousedown] || {{tick}}
|-
| ''mouseup'' || Mouse button released || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseup mouseup] || {{tick}}
|-
| ''click'' || ''mousedown'' + ''mouseup'' have been triggered for this element without moving more than a certain maximum distance || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-click click] || {{tick}}
|-
| ''dblclick'' || Two ''click'' events have been triggered for this element without moving more than a certain maximum distance and time limit || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-dblclick dblclick] || {{tick}}
|-
| ''drag'' || The mouse has been moved with a button down. After dragging has started above an element, all consecutive ''drag'' events are sent to this element even if the mouse leaves its area || || {{tick}}
|-
| ''wheel'' || Mouse wheel rotated (see deltaY for direction) || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-wheel wheel] || {{tick}}
|-
| ''mousemove'' || Mouse has moved while beeing inside the area of the target element. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mousemove mousemove] || {{tick}}
|-
| ''mouseover'' || Mouse has entered a child or the element itself. ''mouseover'' is also triggered if the mouse moves from one child element to another. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseover mouseover] || {{tick}}
|-
| ''mouseout'' || Mouse has left a child or the element itself. ''mouseout'' is also triggered if the mouse moves from one child element to another. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseout mouseout] || {{tick}}
|-
| ''mouseenter'' || Mouse has entered a child or the element itself. In contrary to ''mouseover'', ''mouseenter'' is not triggered if the mouse moves from one child element to another, but only the first time the element or one of its children is entered. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseenter mouseenter] || {{cross}}
|-
| ''mouseleave'' || Mouse has left the element and all of its children. In contrary to ''mouseout'', ''mouseleave'' is not triggered if the mouse moves from one child element to another, but only if the mouse moves outside the element and all its children. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseleave mouseleave] || {{cross}}
|}

= Example Code =
(Note that this example makes use of advanced Nasal concepts, such as anonymous functions, method chaining and lots of embedded/inline code):
<syntaxhighlight lang="nasal">
# Canvas GUI demo
#
# Shows an icon in the top-right corner which upon click opens a simple window
#

var dlg = canvas.Window.new([32,32]);
dlg.setInt("tf/t[1]", 4)
.setInt("right", 4);
var my_canvas = dlg.createCanvas()
.set("background", "rgba(0,0,0,0)");
var root = my_canvas.createGroup();
canvas.parsesvg(root, "gui/dialogs/images/icon-aircraft.svg");

my_canvas.addEventListener("click", func
{
var dlg = canvas.Window.new([400,300], "dialog");
var my_canvas = dlg.createCanvas()
.set("background", "#f2f1f0");
var root = my_canvas.createGroup();
root.addEventListener("click", func(e) {
printf( "click: screen(%.1f|%.1f) client(%.1f|%.1f) click count = %d",
e.screenX, e.screenY,
e.clientX, e.clientY,
e.click_count );
});
root.addEventListener("dblclick", func(e) {
printf( "dblclick: screen(%.1f|%.1f) client(%.1f|%.1f)",
e.screenX, e.screenY,
e.clientX, e.clientY );
});
root.addEventListener("wheel", func(e) {
printf( "wheel: screen(%.1f|%.1f) client(%.1f|%.1f) delta = %.1f",
e.screenX, e.screenY,
e.clientX, e.clientY,
e.deltaY );
});
var text =
root.createChild("text")
.setText( "This could be used for building an 'Aircraft Help' dialog.\n"
~ "You can also #use it to play around with the new Canvas system :). β" )
.setTranslation(10, 30)
.set("alignment", "left-top")
.set("character-size", 14)
.set("font", "LiberationFonts/LiberationSans-Regular.ttf")
.set("max-width", 380)
.set("fill", "black");
var text_move =
root.createChild("text")
.setText("Mouse moved over text...")
.setTranslation(20, 200)
.set("alignment", "left-center")
.set("character-size", 15)
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")
.set("fill", "#ff0000")
.hide();
var visible_count = 0;
text.addEventListener("mouseover", func text_move.show());
text.addEventListener("mouseout", func text_move.hide());
});
</syntaxhighlight>

<references/>

Template:Note

2014-08-05T09:26:30Z

TheTom: Remove <div> block and display: inline-block to prevent layoutproblems with infoboxes.

{| cellspacing="0" style="margin:1em 5% 1em 5%; border: 1px solid #1992ff; border-left-width: 10px; min-width: 50%; background-color: #e0f2ff; padding: 2px;"
| style="padding-left:5px;"| '''Note'''&ensp; {{{1|Add message}}}
|}</div>
<noinclude>{{Informative template |1=
__NOTOC__
== Goal ==
Use this template to add a note about something important.

== Usage ==
<nowiki>{{</nowiki>'''note'''<nowiki>|</nowiki>message<nowiki>}}</nowiki>

== Example ==
<nowiki>{{note|The gyro compass may drift. Compare the gyro compass against the wet compass at regular intervals.}}</nowiki>
{{note|The gyro compass may drift. Compare the gyro compass against the wet compass at regular intervals.}}

== Related templates ==
* {{tl|caution}} – When there might be damages to the virtual aircraft or to real equipment
* {{tl|tip}} – For helpful tips
* {{tl|warning}} – When a virtual aircraft might crash or when real equipment or ones health might be jeopardized

}}

[[Category:Messagebox templates]]
</noinclude>

Template:Canvas Navigation

2014-07-21T15:04:14Z

TheTom:

{{forum|71|Canvas}}
{{sidebar
| name = Canvas Navigation
| title = Canvas - the FlightGear 2D drawing API
| contentstyle= text-align: left;

| content1 =
* [[Canvas]] - Main Page
* [[Canvas-hackers]] (team clone)
* [[Canvas Development]]
* [[Canvas GUI]]
* [[Canvas Widgets]]
* [[Canvas Maps]]

| heading2 = Frameworks
| content2 =
{{Canvas Frameworks|mode=navbar}}
* [[Canvas Glass Cockpit Efforts]]

| heading3 = Tutorials
| content3 =
* [[Howto:Getting started with Canvas]]
* [[Howto:Adding a canvas to a GUI dialog]] (PUI!)
* [[Howto:Creating a Canvas GUI dialog file]] (New)
* [[Howto:Creating a Canvas GUI Widget]]
* [[Howto:Add a 2D canvas instrument to your aircraft]]
* [[Howto:Parsing 2D Instruments using the Canvas]]
* [[Howto:Creating fullscreen Canvas applications]]
* [[Howto:Use SVG inside a Canvas]]
* [[Howto:Canvas applications as Nasal submodules]]
* [[Howto:Using raster images and nested canvases]]

* [[Howto:Creating a Canvas graph widget]]
* [[Canvas HUD]]
| heading4 = Reference
| content4 =
* [[Canvas Element]]
** [[Canvas Group|Group]]
** [[Canvas Image|Image]]
** [[Canvas Map|Map]]
** [[Canvas Path|Path]]
** [[Canvas Text|Text]]
* [[Canvas Nasal API]]
** [[Canvas MessageBox|MessageBox]]
** [[Canvas Layout System|Layout System]]
* [[Canvas - Event_Handling|Event Handling]]
| heading5 = Related
| content5 =
* [[Canvas Properties]]
* [[Unifying the 2D rendering backend via canvas]]
* [[Howto:Create a 2D drawing API for FlightGear]]
* [[Howto:Use a Camera View in an Instrument]]

| heading6 = To be ported
| content6 =
* [[Navigation display]] {{Progressbar|70}}
* [[Map]] {{Progressbar|80}}
* [[FGCanvas]] {{Progressbar|20}}

| heading7 = Obsolete (deprecated by the Canvas)
| content7 =
* [[Complex Glass Cockpit Avionics]]

}}<includeonly>{{main other|[[Category:Canvas]][[Category:Core development projects]]}}
{{howto other|[[Category:Canvas]][[Category:Howto]]}}</includeonly><noinclude>{{Informative template|1=
== Usage ==
Add the template to the top of the article text.
<nowiki>{{Canvas Navigation}}</nowiki>

Adding the template to an page in the main namespace, the article namespace, or the howto namespace will add [[:Category:Canvas]] to the page. In addition [[:Category:Howto]] will be added to articles in the howto namespace, and [[:Category:Core development projects]] will be added to articles in the main namespace.

}}

[[Category:Navigation templates]]
[[Category:Canvas]]
</noinclude>

Canvas layout system

2014-07-21T15:03:11Z

TheTom: Basic Nasal API documentation

[[Category:Canvas]]
{{Template:Canvas Navigation}}

<syntaxhighlight lang="nasal">
#
# Base class for all widgets/layouts
#
var LayoutItem = {
getCanvas: func(),

setCanvas: func(<Canvas>),

getParent: func(),

setParent: func(<LayoutItem>),

sizeHint: func(),

minimumSize: func(),

maximumSize: func(),

hasHeightForWidth: func(),

heightForWidth: func(<int: width>),

minimumHeightForWidth: func(<int: width>),

setVisible: func(<bool: visible>),

isVisible: func(),

isExplicitlyHidden: func(),

show: func(),

hide: func(),

setGeometry: func([<int: x>, <int: y>, <int: width>, <int: height>]),

geometry: func()
};

#
# Base class for all layouts
#
var Layout = {
parents: [LayoutItem],

# Add an item.
addItem: func(<LayoutItem>),

# Set the spacing/padding between items.
setSpacing: func(<int: space>),

# Get the spacing/padding between items.
spacing: func(),

# Get the number of items (excluding nested items).
count: func(),

# Get the item at the given position.
itemAt: func(<int: index>),

# Remove and get the item at the given position.
takeAt: func(<int: index>),

# Remove the given item from the layout.
removeItem: func(<LayoutItem>),

# Remove all items.
clear: func()
};

#
# Vertical or horizontal box layout
#
var BoxLayout = {
parents: [Layout],

addItem: func(<LayoutItem>[, <int: stretch> = 0]),

addStretch: func([<int: stretch> = 0]),

addSpacing: func(<int: size>),

insertItem: func(<int: index>, <LayoutItem>[, <int: stretch> = 0]),

insertStretch: func(<int: index>[, <int: stretch> = 0]),

insertSpacing: func(<int: index>, <int: size>),

# Set the stretch factor of the item at the given position to <stretch>.
setStretch: func(<int: index>, <int: stretch>),

# Set the stretch factor of the given item to <stretch>
# (if it exists in this layout).
setStretchFactor: func(<LayoutItem>, <int: stretch>),

# Get the stretch factor of the item at the given position.
stretch: func(<int: index>)
};

#
# Horizontal box layout
#
var HBoxLayout = {
parents: [BoxLayout],

# Create a horizontal box layout
new: func()
};

#
# Vertical box layout
#
var VBoxLayout = {
parents: [BoxLayout],

# Create a vertical box layout
new: func()
};
</syntaxhighlight>

Canvas Element

2014-07-18T11:01:26Z

TheTom: Clipping

FlightGear Newsletter June 2014

2014-06-30T22:21:35Z

TheTom: Canvas GUI/MessageBox

{{Newsletter-header|June 2014}}
<div style="border-bottom:3px double #BBB;">
{| width="100%" |
| valign="top" width="33%" |
{{Newsletter-cover-header|Development news}} 
{{Newsletter-cover-item|FlightGear 3.2 - Feature Freeze}} 
{{Newsletter-cover-item|Canvas GUI: Layouting, Widgets and MessageBoxes}} 
{{Newsletter-cover-item|Preview: Aircraft Center - get it on the fly}} 
{{Newsletter-cover-item|Canvas/MapStructure Updates}} 
{{Newsletter-cover-header|Addons and mods}} 
{{Newsletter-cover-item|Damage and disintegration}} 
{{Newsletter-cover-item|Scenesetter}}
| valign="top" width="33%" |
{{Newsletter-cover-header|In the hangar}} 
{{Newsletter-cover-item|Beechcraft Bonanza}} 
{{Newsletter-cover-item|Saab JA-37 Viggen}} 
{{Newsletter-cover-item|Updated P-51D now in git}} 
{{Newsletter-cover-item|Balancing the Boeing 747-400}} 
{{Newsletter-cover-item|Extra500 is updated to production status}}
| valign="top" width="33%" |
{{Newsletter-cover-header|Scenery corner}} 
{{Newsletter-cover-item|USA state capital buildings}} 
{{Newsletter-cover-item|LIPY, a scenery conversion from MSFS}} 
{{Newsletter-cover-item|Reshaping Leipzig/Halle Airport}} 
{{Newsletter-cover-header|Wiki updates}} 
{{Newsletter-cover-item|An updated Weather article}}
|}
</div>

{{Template:Newsletter-article-start|{{{1|FlightGear 3.2 - Feature Freeze}}}|By [[User:t3r|TorstenD]]|Development news}}
On June 17, we entered our scheduled feature freeze state for the next release. Please use the remaining weeks to improve the existing features, harden and cleanup the code, edit the [[Next Changelog|ChangeLog]], improve the Manual, document the undocumented etc. etc. The release branches will be created on July 17th to have the release ready by Aug. 17th.

{{Template:Newsletter-article-start|{{{1|Canvas GUI: Layouting, Widgets and MessageBoxes}}}|By [[User:TheTom|TheTom]]}}

=== Widgets and Layouting ===

[[File:Canvas GUI Demo Dialog.png|300px|thumb|Screen shot showing a simple [[Canvas GUI]] dialog with a handful of [[Canvas Widgets|Button Widgets]].]]

Thanks to the recent work of Tom, the [[Canvas]] system now supports basic widgets and layouting, similar to the Qt [http://qt-project.org/doc/qt-5/layout.html Layouting System]. Using vertical and horizontal box layouts widgets can be placed and sized automatically within the available space. Together with standard widgets like buttons, checkboxes, labels and scroll areas, this is a large step forward in creating a modern, new GUI for FlightGear.

For an example on how to use the new system see [[Howto:Creating a Canvas GUI dialog file]].

=== MessageBoxes ===

Based on the new widgets and layouts, [[Canvas MessageBox|Message Boxes]] provide a simple way to report information to the user or ask him simple questions with a standardized appearance. Selecting from a predefined set of icons and buttons showing a message can be as simple as:

<syntaxhighlight lang="nasal">
canvas.MessageBox.information("Success", "The operation has successfully completed.");
</syntaxhighlight>

Get more information on how to [[Canvas MessageBox|create Message Boxes on your own...]]

<gallery mode=packed>
Canvas-MessageBox-demo information.png|Reporting information
Canvas-MessageBox-demo warning dont-show-again.png|Showing a warning (allowing the user to not get it reported the next time)
</gallery>

{{Template:Newsletter-article-start|{{{1|Preview: Aircraft Center - get it on the fly}}}|By [[User:TheTom|TheTom]] and [[User:Zakalawe|Zakalawe]]}}

[[File:Aircraft-center-prototype.png|270px|thumb|Canvas dialog showing the prototype for an [[Aircraft Center]] for directly installing/managing aircraft from within FlightGear, an upcoming feature scheduled for FlightGear 3.2, currently being developed by TheTom and Zakalawe]]
The "built-in" GUI/launcher is one of the longest-standing feature requests - but it's not just about the GUI (which is rather straightforward in comparison), but about the simulator never having been developed with this requirement, i.e. run-time reinitialization, in mind - thus, things like "fgrun" (and a plethora of other external launchers) were developed, which acted as a front-end on top of FG, so that FG itself wouldn't need to be changed - i.e. kind of a "remote control" using command line arguments. So it's there for a reason - fgrun uses the FLTK GUI library, which while relatively simple, is much more powerful than our legacy GUI engine, PUI.

Still, people have been asking for this for years, and it's thanks to pretty much a single person, Zakalawe, that switching aircraft is going to become possible pretty soon - he handled all the ugly work of cleaning up the simulator internals to make this happen - it's not exactly glamorous work, you gotta touch a ton of places, and you inevitably introduce a ton of regressions along the way.

And yes, even the legacy FG GUI is entirely based on XML and configurable through just editiing XML files - but the collection of "widgets" (GUI controls like buttons, checkboxes, labels etc) is extremely small and very inflexible.

This is something that is currently being addressed by TheTom and Zakalawe, who've both been working on a new Canvas GUI, and a new Canvas GUI dialog called "Aircraft Center", which -while still experimental- is intended to eventually allow end-users to easily download/install aircraft right within the simulator, and also switch between aircraft at run-time without having to exit/restart the simulator.

Thus, adopting Canvas is going to address a number of long-standing issues, but it's obviously a process that only just got started, and it will not happen overnight - 2-3 release cycles are not far-fetched, that's how long the whole migration could very well take, unless there are more people interested in helping.

{{Newsletter-article-start|Canvas/MapStructure Updates|By [[User:Hooray|Hooray]] and [[User:Philosopher|Philosopher]]}}

The upcoming FlightGear version (3.2) will contain a canvas-based map dialog, including a modular "plugin" system for creating custom map layers and charts with roughly ~50 lines of code, most of it boilerplate. This is entirely XML/Nasal based (scripted) - symbols can be pretty much anything, raster or vector images (png or svg), but even animated. Styling can be customized, too.

For more info, I suggest to check out: [[MapStructure#Porting the map dialog]]

<gallery mode=packed>
MapStructureDialog.png|You can basically create arbitrary layers, even for custom objects/positions
Map-canvas-chain-home-editor.png|The same method can be used for creating a "live" radar display
MapStructure-TFC-Troubleshooting.png|
Map-canvas-dialog-storms-overlay.png|But maps and layers can be fairly sophisticated, too - all 100% scripted
</gallery>

As long as you use the MapStructure framework, all layers can be easily used in dialogs AND instruments Coding-wise, there isn't too much involved these days, all the details are covered in the MapStructure article.

[[File:Map-canvas-mapstructure-performance.png|thumb|stress-testing [[MapStructure]] using the ufo @ KSFO circling at 2000 kts in a climb, see [http://forum.flightgear.org/viewtopic.php?f=71&t=21509&p=211611#p211611] ]]

Now that Hyde has committed Philosopher's latest changes, I'd be interested in getting some more feedback on performance.
Here, I am using the ufo @ksfo circling in a shuttle climb at >= 2000 kts GS and getting roughly 30 fps and 40-60 ms.

The recent GUI work committed by TheTom means that we can phase out the PUI map-canvas.xml dialog and create the whole dialog procedurally using a native canvas window, because we really only need two types of widgets: buttons and checkboxes, which are both supported now, thanks to the new [[Aircraft Center]].

We're also in the process of turning our map-canvas.xml dialog into a generic, and reusable, widget for $FG_ROOT/Nasal/canvas/gui/widgets - the widget is using the new Layout engine to align other widgets (checkboxes & buttons for now). And one of our goals is to also modernize airports.xml (the airport selection dialog) such that it can use MapStructure. The simplest way would be to simply turn the PUI CanvasWidget into a Canvas.Window() so that layouting etc works as expected, and so that we can simply show the new scripted MapWidget there.

<gallery mode=packed>
Native Canvas MapWidget Dialog.png|Native Canvas MapWidget dialog using just Canvas Widgets, the Map has been turned into a Canvas Widget itself, so that it can be easily embedded in other dialogs (obviously the whole thing still needs to be cleaned up, layouting isn't currently used yet). See [http://forum.flightgear.org/viewtopic.php?f=71&t=23391&p=213435#p213435]
Native Canvas MapWidget Dialog Prototyping.png|More Canvas/MapWidget prototyping. See [http://forum.flightgear.org/viewtopic.php?f=71&t=23391&p=213435#p213435]
MapStructure dialog with clipping and event handling applied.png|Screen shot showing TheTom's modified demo dialog with a [[MapStructure]] based map that has clipping and event handling applied, i.e. can respond to common mouse events in order to either display tooltips or support drag&drop-style GUI dialogs for editing map-like displays, e.g. for creating an [[Advanced weather]] GUI[http://forum.flightgear.org/viewtopic.php?f=71&t=17642]. Particular care must be taken to formalize z-index handling (rendering priority) for each MapStructure layer, which is something we still need to work out, especially for possibly overlapping symbols...
MapStructure-based Weather Editor Widget for Canvas using interactive and editable lcontroller files.png|This screen shot shows an experimental MapStructure-based Weather Editor Widget for [[Canvas]] using interactive and editable lcontroller files that respond to GUI events so that map symbols can be interactively placed on a map.
The legacy PUI-airport selection dialog using the new Canvas MapWidget.png|This is a screen shot showing Stuart's PUI/XML based airport selection dialog with an embedded Canvas MapWidget that is driven by Philosopher's [[MapStructure]] framework using TheTom's latest GUI/Layouting changes (e.g. checkbox widgets).

</gallery>

{{Newsletter-article-start|Boeing 777 EFB prototype|By [[User:I-NEMO|I-NEMO]]}}
[[File:777-EFB-MAIN.png|thumb|777-200ER EFB [http://forum.flightgear.org/viewtopic.php?f=71&t=23196]]]
[[File:777-EFB-AIRPORT-SEARCH.png|thumb|777-200 EFB AIRPORT SEARCH, see [http://forum.flightgear.org/viewtopic.php?f=71&t=23196&p=211410#p211410]]]

I-NEMO has started porting his 777/EFB prototype to [[Canvas]]

As I wrote several times, I finally decided to put hands on the EFB (Reason: No one ever took care of developing an EFB for the 777; a 'working' EFB, though) with two (2) main goals in mind:
# do something to compensate for the lacking of an EFB inside the Boeing 777 Seattle.
# actually try (I repeat it: 'try') to learn some first essentials of nasal.

This Seattle EFB is just a 'rude' one: with this term, I mean (as a word's pun) 'unpolite'. I'm perfectly aware that the coding is horrible, clumsy, repetitive, silly and very, very far from what it should be. My first aim was simply to have a somehow 'working' EFB inside the Seattle's Cockpit. I do not pretend that current 777's EFB.nas is a piece of nice software; but - to my initial purpose - it works. Not completely, not nicely, not properly...but it's a starting point. At least, it works...
Current development ('modernisation' phase) of the '''Boeing 777 Seattle's EFB''' is going on nicely; the code is shorter, more readable and cleaner.
I have not finished it, yet (I'd say that it's almost 50% done).

At the moment I have a single Canvas group (i.e., ''EFB_group''), with 5 children: the text-matrix (16 left lines, 16 right lines), a Title line , an Helper line and the Display. 
The ''Display'' element is then textured with all the various pages' textures, called by the page-handler (''see'' here below). 
Currently, I'm using the .jpg textures which I had previously generated through Photoshop; in the future they might be replaced by .svg files, depending from actual interactive use of some graphical objects (a few EFB pages do need interaction with graphical parts). Besides - if i'm not wrong - I've read somewhere on the FGWiki that gradients are not handled by the SVG parser...and I do like to use some gradients effects (antialiasing and such) to achieve a sort of realism on the displays.

that's the current status of the new 777 ''Seattle'''s EFB: it's still far from being perfect, but - as a newbie - I'm quite satisfied for the moment: I need to finish the first version fairly soon, because my to-do-list is long (I have to re-model all the aircraft fuselage [original model has wrong measures, ''sigh!''], produce better gears and flight-control surfaces model & animations in Blender, and then to produce a new Paint-Kit in Photoshop; then all 3D models optimizations...and so forth; of course, we also have to take care of CDU, which will interface with the EFB. So, the job is still very, very long...

The current EFB code is heavily focused on rendering raster images, which can be retained obviously, but in FG, we have additional means to render airport information that is 100% in sync with the FG side of things (navdb). 
 
For instance, we are going to "port" the airport-selection dialog to move rendering of airports/runways/taxiways/parking spots into dedicated MapStructure layers that can be properly styled and customized: [[Canvas_MapStructure#Porting_the_airports.xml_dialog]] 
 
[[File:Airport-selection-dialog.png|250px]] 
 
As you can probably tell, these kinds of layers would be very useful for any kind of EFB related application. 
 
As long as the underlying design for a "page"-based MFD framework is sufficiently generic, we can easily replace/augment raster images and procedurally created charts - we could even use the built-in support for fetching via HTTP to download images on-line. In fact, we could then even extend Canvas to directly support rendering PDFs (OSG supports this out-of-the-box), this would make many steps unnecessary, because we could directly access [http://airnav.com http://airnav.com] without having to download/convert/ship any imagery. The code required to pull this off would be very compact in comparison.

Learn more at [[Canvas EFB Framework]] or follow the [http://forum.flightgear.org/viewtopic.php?f=71&t=23204 forum discussion]...

{{Newsletter-article-start|Towards an Aircraft-agnostic MFD Framework|By [[User:Hooray|Hooray]]}}
Given the recent trend of having several MFD-related efforts without any kind of collaboration/code reuse going on here among our contributors (PFD, ND, Avidyne Entegra R9, EFB), I have started prototyping a generic MFD framework that is purely XML-based, inspired by discussions we've had over the last couple of weeks, and lessons learnt from the missions subsystem.

It is intended to:
* support multiple independent instances
* be totally aircraft agnostic
* support a pure dialog-driven mode
* support skinning/theming

This is supposed to support modeling complex avionics like a PFD, ND, EFB, CDU etc - and, eventually, also the Avidyne Entegra R9. It's currently just a prototype, but it gets away with very little code and we really only need a few more "skins" for common avionics. I am willing to extend this over time and help maintain it if people can agree to use something like this. It should be straightforward to allow such "MFDs" to be reloaded from disk at run-time, i.e. for more rapid prototyping.

{{Note|This is work in progress - the idea is to identify required building blocks to easily specify most MFD functionality in a generic fashion, without requiring a ton of custom Nasal code and without being specific to a single type of MFD. The whole concept is based on [[FlightGear_Missions_and_Adventures#XML_Extension_Framework]], i.e. providing a Nasal-space mechanism to expose and re-define building blocks to XML space.

The Nasal/Canvas data structures will be transparently created and compiled for each MFD. Each MFD consists of an arbitrary number of buttons, modes and pages. Each MFD can be instantiated multiple times, and each MFD is designed to be aircraft/instrument agnostic, i.e. also works just in a conventional Canvas dialog. Buttons can trigger and switch between modes, and modes may have pages (conventionally implemented through a single SVG file). Each page consists of an arbitrary number of page elements, which can in turn be animated/updated via listeners and timers. Should look at existing displays, especially the [[NavDisplay]] and the update() method in navdisplay.mfd, but the most complete test-case would probably be the [[Avidyne Entegra R9]] }}

<gallery mode=packed>
Gpsmap196-canvas-panel-page.png|F-JJTH has updated the SVG file implementing the panel page for the [[Garmin GPSMap 196]].
Canvas-mfd-framework-prototyping.png|This is an adapted version of the [[Garmin GPSMap 196]] that is currently being developed by F-JJTH. Here, the whole instrument is entirely set up in XML space, including buttons/event handling, but also the embedded canvas region that serves as the 'screen'. The idea is to allow arbitrary MFDs to be specified in an aircraft-agnostic fashion, including displays like a PFD, [[NavDisplay]] or EFB. For details, please see [[Canvas Glass Cockpit Efforts]].
Canvas-mfd-framework-prototyping-with-mapstructure.png|This demonstrates how a purely XML-based MFD framework can instantiate dynamic [[MapStructure]] layers - none of this involves any [[Nasal]] coding now, it's just an XML file - to learn more, see [[Canvas Glass Cockpit Efforts]].
Canvas-mfd-framework-prototyping-with-mapstructure-with-kln89-skin.png|This screen shot shows the texture of the hard-coded KLN89 instrument used as a skin/theme for the MFD instrument, with a MapStructure-powered map shown.
</gallery>

{{Newsletter-article-start|Logo proposal|By [[User:Aepcam|Aepcam]]}}
This is a new logo badge concept proposal for FlightGear designed by Michat.

[[File:Fglogo1.png]]
[[File:Fglogowiki.png]]
[[File:Fglogoforum.png]]

{{Newsletter-article-start|Damage and disintegration|By [[User:Algernon|Algernon]]|FlightGear addons and mods}}
{{#ev:youtube|OpwNaoO3xMQ|200|right|Tomaskom's V-1 used in anger over London}}
{{#ev:youtube|H4XDuLo35ks|200|right|Victor V2.0 damage script causing a catastrophic failure and fire}}
{{#ev:youtube|uLojBI7ezdM|200|right|L-159 disintegration}}
The development team at FGUK have been experimenting with modelling aircraft damage in a number of different ways. First of all, Tomaskom has used the particle system carefully to produce visually impressive fireballs and smoke columns with very little FPS impact. First seen in his V-1, we hope to adapt this to simulate realistic fireballs for ground impacts (where appropriate). For the moment, it explodes with the full force of a V-1's explosive payload. On the right is a video excerpt from the #FlightNight which Tom organised to debut the V-1, where we all had '''way''' too much fun bombing London. As you can see, the smoke is visible from quite a long way away from the impact, and despite two fires burning with huge smoke columns, and over ten multiplayer aircraft within model range, the frame rates are still more than acceptable. StuartC has already integrated the explosion and fireball into several development aircraft, and we expect eventually to combine it with the disintegration code and make the size of the explosion dependent on fuel load etc.

In a separate development, Algernon's work on the Victor V2.0(YASim) now includes modelled damage, a collection of Nasal scripts, some modified from existing FlightGear staples, which detects irregularities such as component failures, birdstrikes and combat weapon damage and adversely affects system performance and reliability accordingly. Unserviceability often follows, using the existing FlightGear failures system, and compatibility will be maintained as the failures system is improved. The damage script also calculates probabilites for chain reaction damage - for instance, an explosion or serious fire in one Victor engine will usually have an effect on the other. In extreme circumstances, an explosion will trigger further explosions and destroy the aircraft. The second video on the right shows a serious induced explosion on the Victor's number one engine at night. Some fine-tuning of the Rembrandt light has been carried out since this video was shot, so apologies for the visible cut-off.

Finally, and most spectacularly, Tomaskom has demonstrated the disintegration capabilities of his L-159, which is under development. Hopefully, he will explain all here before publication date.

{{Newsletter-article-start|Scenesetter|By [[User:Algernon|Algernon]]}}
Scenesetter is a piece of code by Algernon, very early in development but already quite effective, which can effect changes to the time and weather from an AI scenario synchronously with other MP players. A crude proof of concept was used in the recent FGUK #FlightNight "British Weather", where pilots visited different airfields with various unpleasant flying conditions. Scenesetter pushes METAR strings to the FlightGear weather system based on the location of an associated Navaid, establishing a circular zone of a specified radius around it in which METAR will be changed. Start time can be specified too, either by providing a local start time or a local time offset (useful for Multiplayer use where players will not all start the AI scenario at precisely the same time).

{{Newsletter-article-start|Beechcraft Bonanza|By [[User:Flyingfisch|Flyingfisch]]|In the hangar}}
Flyingfisch is building the Beechcraft A35 Bonanza for Flightgear. Some pictures:
<gallery mode=packed>
Beech_bonanza_with_panel_lights_on.png|Panel lighting
Bonanza rbf.png|Remember to do your pre-flight check before startup!
Bonanza at sunrise.png|The Beech Bonanza at Kent State University (1G3) just before sunrise
Bonanza interior at sunrise.png|The interior of the Bonanza at sunrise.
</gallery>

{{Newsletter-article-start|Saab JA-37 Viggen|By [[User:Necolatis|Necolatis]]}}
The Swedish fighter jet [[Saab JA-37 Viggen]] has been updated, since it was included in FlightGear 3.0. More instruments, additional liveries, aerodynamic response to payload and tooltips on instruments. Option for automatic reverse thrust at touchdown, selection of HUD brightness, disabling of structural damage. HUD can now switch to imperial units and show MP and AI aircraft and closest airport. The aircraft now also has multiplayer sounds and better cockpit view helps seeing the landing strip. Support for FG 2.8 by deleting a small section in an xml file. Also worth mentioning is countless bug-fixes and improvements, e.g. better handling at high altitudes and a bug fix in the lift force formula.

[[File:Saab JA-37 Viggen Blue Peter Livery.png|Blå Petter Livery for JA-37]]

{{Newsletter-article-start|Updated P-51D now in git|By [[User:hvengel|hvengel]]}}
The new 3D exterior model for the [[North American P-51 Mustang|North American P-51D Mustang]] is now in git and under active development. It is currently in gray primer waiting for the UV map to be finalized. It is now fully integrated into the existing FDM. Extensive new animation work has been done including animated trim tabs and a fully functional canopy. Here are some screen shots taken in sim for your enjoyment.

<gallery mode=packed heights=250px>
P-51D testing it's guns before a flight..jpg|P-51D testing it's guns before a flight.
P-51D trim tab animation..jpg|P-51D trim tab animation.
</gallery>

{{Newsletter-article-start|Balancing the Boeing 747-400|By [[User:Gijs|Gijs]]}}
After he started developing the [[Boeing 747-400]] as a hobby project six years ago, Gijs finally managed to get the weight and balancing right. The center of gravity is now within 0.05% MAC (40 cm) of the published values.

Make sure to use the new Fuel and Payload dialog to fill your fuel tanks. There is a slider and button that will nicely distribute a specified amount of fuel, while making sure the CoG stays within the operational limits. Before takeoff, check the Takeoff Reference page on the CDU to find the required stab trim units (your current setting is displayed to the left of the throttle quadrant). When you set your trim properly, you can almost relax your yoke to the neutral position after rotate. There's still some FDM work left to fine-tune this.

The updated 747-400 is already available through Git and will be on the download page when FlightGear 3.2 is released.

{{Newsletter-article-start|Extra500 is updated to production status|By [[User:Evandenberg|Evandenberg]]}}
The [[Extra EA-500]] is updated and has reached "production status"! Just a short list of changes for release 1.1.0:
* Engine+fuel: realistic flame-out, fuel flow to collector compartment, anti ice influence on TOT, improved oil press and temp model 
* Aerodynamics: flap performance, elevator-30deg-flaps authority improvement 
* User interface: interactive checklists 
* Sounds: corrected sounds for test, CWS and AP disc 
* Model: added interior, yokes 
* Avionics: IFD moving map, automatic NAV tuning, automatic NAV switching, magnetic variation fixes 
* Autopilot: added OBS and fly vectors mode, significant improvement of coupled ILS performance
A more extensive list can be found in the "version" file.

This version does perform a bit better on my computer, but this has to do with improvements to FGFS, not of the aircraft model. So if your computer was struggling with the initial version, we recommend to use current FlightGear git/nightly builds or wait until 3.2 comes out!

Please checkout the [[Extra EA-500|Extra500 wiki]] for download instructions and lots of more info.

<gallery mode=packed heights=250px>
File:Extra500 flightgear1.png|Extra500 flying in clouds
Extra500canvas.png|Work has begun to analyze, refactor and generalize useful parts of the [[Avidyne Entegra R9]] to help reuse some code in similar MFD efforts, like the [[Garmin GPSMap 196]] or [[Canvas EFB Framework]]
</gallery>

{{Newsletter-article-start|USA state capital buildings|By [[User:Jonbourg|Jonbourg]]|Scenery corner}}
There is a project to add all the USA state capital buildings into FG. It is discussed in [http://forum.flightgear.org/viewtopic.php?f=5&t=22715&sid=ea847909bde2e1f8ffe5b94bcc673f4f this scenery forum thread]. There is also a wiki page: [[State Capitol Buildings in the United States]]. So far, Idaho, Louisiana & Nebraska have been completed. Hawaii and New York are currently in progress. Please feel free to join in with any other state that has not been done yet. Just let us know through the forum and we will add it to the in progress list.

{{Newsletter-article-start|LIPY, a scenery conversion from MSFS|By [[User:bigstones|bigstones]]}}
This month saw the [http://forum.flightgear.org/viewtopic.php?f=5&t=22623 second "preview" release] of the conversion of a scenery for MS Flight Simulator, [[Falconara Airport]] (ICAO code: LIPY), a small Italian international airport halfway down the Adriatic coast. The original author granted the permission to the conversion and even allowed for it to be included in the FlightGear official [[World Scenery]], at least the GPL compatible parts. This is not a huge limitation though, because most of the material was created from scratch, included pictures taken on purpose at the real airport, with the authorities' collaboration. Copyrighted aerial imagery only include the (unsuable) photoreal ground and some roofs.

[[File:LIPY structures landscape.jpg|650px|right]]
The conversion was made with [[ModelConverterX]], which makes the job partially easier than by [[Howto:Convert objects from X-Plane|the Blender method]], yet it's still needing fixes because of some misunderstandings with the coordinates axes. The author of the tool, though, seems not very concerned and anyway, it's so rare to have a freeware scenery author allow conversions, that the usefulness of this tool would be greatly reduced anyhow, especially if you plan to upload the models to the [[FlightGear Scenery Database]].

The conversion itself, moreover, sure is not the matter of a button press. MSFS scenery are often packed and "compiled" in *.BGL files such that independent, far objects with the same materials and same LOD level (Level Of Detail) are bound together. This is clearly against FG's way, in which each new scenery generation could change the relative heights, and however MSFS airports are flat, while in FG they're all sloped. A similar thing happens with the texture maps. This basically means that you'll have to join all these objects and split them again based on the model they belong to (e.g. tower, terminal, hangars...)

Another issue with textures is that in FG it's good practice - recommended if not mandatory - to have 2 separate texture maps for the same object, if some parts are translucent. This means that without rebuilding all the texture maps [http://forum.flightgear.org/viewtopic.php?f=5&t=22707 you'll likely get artifacts]. Then, you'd have to add the Rembrandt lights if you want, and also the lightmaps (MSFS uses night textures, but Gimp can easily convert them). This whole experience can be summed up in the following quote:

{{cquote|I really wanted to have this scenery in FG because it's my home base, and seeing it ready and so well done just made me want it. However, even if still easier than making it from scratch (even if reusing the textures), I'd have to think well if I had to do this again.|bigstones, maintainer of the conversion}}

{{Newsletter-article-start|Reshaping Leipzig/Halle Airport|By [[User:August|August]]}}
[[File:2014 new-layout-EDDP 05.jpg|650px|right]]
In FlightGear Germany's second largest cargo airport [[EDDP]] is well known as a detailed model accessible for everybody via [[TerraSync]]. Until 2013 it was famous for its regular ATC-events. It has been updated several times, at least 2012 by users D-STHO and August. When FlightGear 3.0 was published the airport layout changed from the old 810-standard to the new 850-standard. But the update (based on a taxiway layout modelled for X-Plane) turned out to be very imperfect. Many aprons and taxiways did not exist, dimensions did not appear to be correct and many new facilities which had been added at the real-world airport had not been taken into account. So maintainer August decided to redesign the whole airport from the scratch using [[WorldEditor]].
Pilots and developers are now invited to test the new airport model which includes further improvements like predefined STAR-, -SID and Transition procedures and hundreds of replaced Static- and Shared Models. The project will be published on TerraSync as soon as all defects are discovered remedied.

Developer Version:
'''git clone''' [https://gitorious.org/eddp-custom-scenery/eddp-custom-scenery/ https://gitorious.org/eddp-custom-scenery/eddp-custom-scenery/]

Feedback is welcome at [[User talk:August|August's wiki page]].
<gallery mode=packed>
2014 new-layout-EDDP 04.jpg|Taxiway T - new ground textures
2014 new-layout-EDDP 01.jpg|Runway 26L with DHL-area
2014 new-layout-EDDP 02.jpg|Apron 4
</gallery>

{{Newsletter-article-start|An updated Weather article|By [[User:bigstones|bigstones]]|Wiki updates}}
The [[Weather]] wiki article went through a wide extension. Although Advanced Weather was released quite a while ago, its usage has never been explained in the wiki, and some thorough instructions were available only in a readme in the "docs" folder of the base package which is not commonly explored by users, while the wiki article [[Advanced weather]] is more about the project than the usage.

AW's advanced configuration is known to be not easy. So, if you always only used the weather selection menu and want to know more, or want to understand what the options actually do and how you can combine them, the [[Weather]] article has now been updated with some hints and basic notions extracted from experience and the original documentation, and quality checked by the author of the AW weather engine.

{{Newsletter-article-start|Translators required|}}
{|
|[[File:en.gif]]
|The FlightGear Wiki still needs help for translating it into various languages. If you are interested in making the FlightGear Wiki multi-language then start at [[Help:Translate]].
|-
|[[File:de.gif]]
|Das FlightGear Wiki benötigt immer noch Hilfe bei der Übersetzung in verschiedene Sprachen. Wenn Du Interesse daran hast, das FlightGear Wiki Mehrsprachig zu machen, dann fang doch mit [[:de:Help:Übersetzen|Help:Übersetzen]] an.
|-
|[[File:nl.gif]]
|De FlightGear Wiki kan nog steed hulp gebruiken bij het vertalen van artikelen. Als je interesse hebt om de wiki meertalig te maken, raden we je aan om een kijkje te nemen bij [[:nl:Help:Vertalen|Help:Vertalen]].
|-
|[[File:es.gif]]
|La FlightGear wiki todavía necesita ayuda para traducirla a varios lenguajes. Si estás interesado en hacer la FlightGear wiki multilingüe, entonces comienza en [[:es:Help:Traducir|Help:Traducir]].
|}

{{Newsletter-article-start|Call for volunteers||And finally...}}
* The [[TerraGear]] maintainers are looking for volunteers to help with development on the next world scenery project. If you've ever wondered how a full 3D model of earth can be generated from raw data, now is your chance. See the plan at [[TerraGear roadmap]].

[[Category:FlightGear Newsletter|2014 06]]
[[Category:Changes after 3.00]]

File:Aircraft-center-prototype.png

2014-06-30T21:36:25Z

TheTom: TheTom uploaded a new version of "File:Aircraft-center-prototype.png"

=={{int:filedesc}}==
{{Information
|description={{en|1=Canvas dialog showing the prototype for an [[Aircraft Center]] for directly installing/managing aircraft from within FlightGear, an upcoming feature scheduled for FlightGear 3.2, currently being developed by TheTom and Zakalawe}}
|date=2014-06-13 20:37:55
|source={{own}}
|author=[[User:Hooray|Hooray]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Canvas development projects]]

File:Canvas VBoxLayout Demo Dialog.png

2014-06-30T21:08:31Z

TheTom: TheTom uploaded a new version of "File:Canvas VBoxLayout Demo Dialog.png"

=={{int:filedesc}}==
{{Information
|description={{en|1=Screen shot showing a simple [[Canvas GUI]] dialog with a handful of [[Canvas Widgets|Button Widgets]].}}
|date=2014-06-29 20:02:36
|source={{own}}
|author=[[User:Hooray|Hooray]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Canvas development projects]]

File:Canvas GUI Demo Dialog.png

2014-06-30T21:05:12Z

TheTom: TheTom moved page File:Canvas GUI Demo Dialog.png to File:Canvas VBoxLayout Demo Dialog.png

#REDIRECT [[File:Canvas VBoxLayout Demo Dialog.png]]

File:Canvas VBoxLayout Demo Dialog.png

2014-06-30T21:04:57Z

TheTom: TheTom moved page File:Canvas GUI Demo Dialog.png to File:Canvas VBoxLayout Demo Dialog.png

Howto:Creating a Canvas GUI dialog file

2014-06-30T21:00:15Z

TheTom: Demo code tweaks/prepare for better screenshot

{{Stub}}

[[File:Canvas GUI Demo Dialog.png|300px|thumb|Screen shot showing a simple [[Canvas GUI]] dialog with a handful of [[Canvas Widgets|Button Widgets]] arranged with a vertical/vbox layout.]]
{{Canvas Navigation}}

'''Targeted FlightGear versions: >= 3.20'''

== Editing Translations/en/menu.xml ==
Navigate to the sub-menu where you'd like to add your new dialog, e.g. "Equipment" in this case, and then add a key:
<syntaxhighlight lang="xml">
<equipment>Equipment</equipment>
<canvas-demo-dialog>Canvas Demo Dialog</canvas-demo-dialog>
</syntaxhighlight>

== Editing gui/menubar.xml ==
Next, open $FG_ROOT/gui/menubar.xml and navigate to the corresponding sub-menu and add a new item/binding to load your dialog:
<syntaxhighlight lang="xml">
<item>
<name>canvas-demo-dialog</name>
<binding>
<command>nasal</command>
<script>
canvas.loadDialog("CanvasDemo");
</script>
</binding>
</item>
</syntaxhighlight>

== Creating the actual dialog file ==
{{Note|These dialog files can be edited at run-time and simply closed/re-opened, because the Canvas system will reload them from disk whenever the menu binding is triggered. So this is very convenient for quickly developing and testing your dialogs. For testing purposes, you can also paste the snippet into your [[Nasal Console]] and directly execute it.}}
Next, open/create $FG_ROOT/Nasal/canvas/gui/dialogs/CanvasDemo.nas and add some boilerplate code:
<syntaxhighlight lang="nasal">
var DemoDialog = {
new: func
{
var m = {
parents: [DemoDialog],
_dlg: canvas.Window.new([140,160], "dialog")
.set("title", "VBoxLayout")
.set("resize", 1),
};

m._dlg.getCanvas(1)
.set("background", canvas.style.getColor("bg_color"));
m._root = m._dlg.getCanvas().createGroup();

var vbox = canvas.VBoxLayout.new();
m._dlg.setLayout(vbox);

# this is where you can add widgets from $FG_ROOT/Nasal/canvas/gui/widgets, e.g.:
for(var i = 0; i < 5; i += 1 )
vbox.addItem(
canvas.gui.widgets.Button.new(m._root, canvas.style, {})
.setText("Button #" ~ i)
);

var hint = vbox.sizeHint();
hint[0] = math.max(140, hint[0]);
m._dlg.setSize(hint);

return m;
},
};

var demo = DemoDialog.new();</syntaxhighlight>

Finally, start FlightGear and open your new dialog

== Adding Widgets ==
In order to keep your dialog sufficiently generic, you'll want to refrain from adding too much custom functionality to it, and instead decompose your functionality into a collection of '''widgets'''. Widgets are GUI controls like a label, button, checkbox etc - i.e. these widgets have a certain appearance and may respond to events such as being clicked for example. Whenever you create custom widgets instead of adding all the code to a single dialog, you'll end up with reusable components that can be easily other in other dialogs. In addition, you are making sure to establish a losely-coupled design, so that your widgets are sufficient generic and do not contain any use-case specific logic.

This means for example that a generic '''PropertyBrowser''' could be easily reused in other dialogs/windows requiring a corresponding property browser. But this also meanns that such a property browser widget should also be modularized, i.e. by using a lower-level '''ListView''' or '''TreeView''' widget and merely parameterizing that by showing properties. This approach has the added advantage that the corresponding '''ListView/TreeView''' widgets could be re-used in other places, such as for example an aircraft list, a [[Nasal Browser|Nasal Namespace Browser]].

Likewise, a widget-focused approach means that useful functionality like a [[Interactive Nasal REPL]] can be easily used in other places, without developers having to do any refactoring.

We're also trying to make sure that Canvas Widgets can be easily used not just by GUI dialogs but also by Canvas-based instruments/MFDs - without any code duplication or Copy&Paste being required.

== Using Layouts ==
{{Note|This section still needs to be written (volunteers invivted to help!)-In the meantime, please refer to $FG_ROOT/Nasal/canvas/gui/dialogs/AircraftCenter.nas}}

== Using Styling ==
{{Note|This section still needs to be written (volunteers invivted to help!)-In the meantime, please refer to $FG_ROOT/Nasal/canvas/gui/styles/DefaultStyle.nas}}

FlightGear Newsletter June 2014

2014-06-30T20:43:21Z

TheTom: Canvas cleanup/restructuring - more to come...

{{Newsletter-header|June 2014}}
<div style="border-bottom:3px double #BBB;">
{| width="100%" |
| valign="top" width="33%" |
{{Newsletter-cover-header|Development news}} 
{{Newsletter-cover-item|FlightGear 3.2 - Feature Freeze}} 
{{Newsletter-cover-item|Canvas GUI: Layouting, Widgets and MessageBoxes}} 
{{Newsletter-cover-item|Preview: Aircraft Center - get it on the fly}} 
{{Newsletter-cover-item|Logo proposal}} 
{{Newsletter-cover-header|Addons and mods}} 
{{Newsletter-cover-item|Damage and disintegration}} 
{{Newsletter-cover-item|Scenesetter}}
| valign="top" width="33%" |
{{Newsletter-cover-header|In the hangar}} 
{{Newsletter-cover-item|Beechcraft Bonanza}} 
{{Newsletter-cover-item|Saab JA-37 Viggen}} 
{{Newsletter-cover-item|Updated P-51D now in git}} 
{{Newsletter-cover-item|Balancing the Boeing 747-400}} 
{{Newsletter-cover-item|Extra500 is updated to production status}}
| valign="top" width="33%" |
{{Newsletter-cover-header|Scenery corner}} 
{{Newsletter-cover-item|USA state capital buildings}} 
{{Newsletter-cover-item|LIPY, a scenery conversion from MSFS}} 
{{Newsletter-cover-item|Reshaping Leipzig/Halle Airport}} 
{{Newsletter-cover-header|Wiki updates}} 
{{Newsletter-cover-item|An updated Weather article}}
|}
</div>

{{Template:Newsletter-article-start|{{{1|FlightGear 3.2 - Feature Freeze}}}|By [[User:t3r|TorstenD]]|Development news}}
On June 17, we entered our scheduled feature freeze state for the next release. Please use the remaining weeks to improve the existing features, harden and cleanup the code, edit the [[Next Changelog|ChangeLog]], improve the Manual, document the undocumented etc. etc. The release branches will be created on July 17th to have the release ready by Aug. 17th.

{{Template:Newsletter-article-start|{{{1|Canvas GUI: Layouting, Widgets and MessageBoxes}}}|By [[User:TheTom|TheTom]]}}
Thanks to Tom's and James' recent work on the upcoming [[Aircraft Center]] for downloading and switching between aircraft without having to exit FlightGear, beginning with FlightGear 3.2, FlightGear's [[Canvas]]-based GUI will contain support for so called [[Canvas MessageBox|Message Boxes]]:
{|
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo information.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.information("Success", "The operation has successfully completed.");
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo question.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.question(
"Do you want it?",
"The question is: Do you want to get a real question?.",
func(sel)
{
if( sel == canvas.MessageBox.Yes )
print("I only know that the answer is 42.");
else
print("Ok, I will not give you a real question.");
}
);
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo warning dont-show-again.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.warning(
"Warning...",
"Have you read this warning? If you want it will not be shown again.",
func(sel)
{
if( sel != canvas.MessageBox.Ok )
return;

print("You have been warned. Let the games begin...");
},
canvas.MessageBox.Ok
| canvas.MessageBox.Cancel
| canvas.MessageBox.DontShowAgain
);
</syntaxhighlight>
|}

[[File:Canvas GUI Demo Dialog.png|300px|thumb|Screen shot showing a simple [[Canvas GUI]] dialog with a handful of [[Canvas Widgets|Button Widgets]].]]

For an example see [[Howto:Creating a Canvas GUI dialog file]].

<div style="clear:both;"></div>

{{Template:Newsletter-article-start|{{{1|Preview: Aircraft Center - get it on the fly}}}|By [[User:TheTom|TheTom]] and [[User:Zakalawe|Zakalawe]]}}

[[File:Aircraft-center-prototype.png|270px|thumb|Canvas dialog showing the prototype for an [[Aircraft Center]] for directly installing/managing aircraft from within FlightGear, an upcoming feature scheduled for FlightGear 3.2, currently being developed by TheTom and Zakalawe]]
The "built-in" GUI/launcher is one of the longest-standing feature requests - but it's not just about the GUI (which is rather straightforward in comparison), but about the simulator never having been developed with this requirement, i.e. run-time reinitialization, in mind - thus, things like "fgrun" (and a plethora of other external launchers) were developed, which acted as a front-end on top of FG, so that FG itself wouldn't need to be changed - i.e. kind of a "remote control" using command line arguments. So it's there for a reason - fgrun uses the FLTK GUI library, which while relatively simple, is much more powerful than our legacy GUI engine, PUI.

Still, people have been asking for this for years, and it's thanks to pretty much a single person, Zakalawe, that switching aircraft is going to become possible pretty soon - he handled all the ugly work of cleaning up the simulator internals to make this happen - it's not exactly glamorous work, you gotta touch a ton of places, and you inevitably introduce a ton of regressions along the way.

And yes, even the legacy FG GUI is entirely based on XML and configurable through just editiing XML files - but the collection of "widgets" (GUI controls like buttons, checkboxes, labels etc) is extremely small and very inflexible.

This is something that is currently being addressed by TheTom and Zakalawe, who've both been working on a new Canvas GUI, and a new Canvas GUI dialog called "Aircraft Center", which -while still experimental- is intended to eventually allow end-users to easily download/install aircraft right within the simulator, and also switch between aircraft at run-time without having to exit/restart the simulator.

Thus, adopting Canvas is going to address a number of long-standing issues, but it's obviously a process that only just got started, and it will not happen overnight - 2-3 release cycles are not far-fetched, that's how long the whole migration could very well take, unless there are more people interested in helping.

{{Newsletter-article-start|Logo proposal|By [[User:Aepcam|Aepcam]]}}
This is a new logo badge concept proposal for FlightGear designed by Michat.

[[File:Fglogo1.png]]
[[File:Fglogowiki.png]]
[[File:Fglogoforum.png]]

{{Newsletter-article-start|MapStructure stress-testing|By [[User:Hooray|Hooray]]}}
[[File:Map-canvas-mapstructure-performance.png|thumb|stress-testing [[MapStructure]] using the ufo @ KSFO circling at 2000 kts in a climb, see [http://forum.flightgear.org/viewtopic.php?f=71&t=21509&p=211611#p211611] ]]

{{cquote
|<nowiki>Now that Hyde has committed Philosopher's latest changes, I'd be interested in getting some more feedback on performance.</nowiki> <nowiki>
Here, I am using the ufo @ksfo circling in a shuttle climb at >= 2000 kts GS and getting roughly 30 fps and 40-60 ms.</nowiki>
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=211611#p211611
|title=<nowiki>Re: NavDisplay & MapStructure discussion (previously via PM)</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Tue Jun 03</nowiki>
}}
}}

{{Newsletter-article-start|Boeing 777 EFB prototype|By [[User:I-NEMO|I-NEMO]]}}
[[File:777-EFB-MAIN.png|thumb|777-200ER EFB [http://forum.flightgear.org/viewtopic.php?f=71&t=23196]]]
[[File:777-EFB-AIRPORT-SEARCH.png|thumb|777-200 EFB AIRPORT SEARCH, see [http://forum.flightgear.org/viewtopic.php?f=71&t=23196&p=211410#p211410]]]

I-NEMO has started porting his 777/EFB prototype to [[Canvas]]

As I wrote several times, I finally decided to put hands on the EFB (Reason: No one ever took care of developing an EFB for the 777; a 'working' EFB, though) with two (2) main goals in mind:
# do something to compensate for the lacking of an EFB inside the Boeing 777 Seattle.
# actually try (I repeat it: 'try') to learn some first essentials of nasal.

This Seattle EFB is just a 'rude' one: with this term, I mean (as a word's pun) 'unpolite'. I'm perfectly aware that the coding is horrible, clumsy, repetitive, silly and very, very far from what it should be. My first aim was simply to have a somehow 'working' EFB inside the Seattle's Cockpit. I do not pretend that current 777's EFB.nas is a piece of nice software; but - to my initial purpose - it works. Not completely, not nicely, not properly...but it's a starting point. At least, it works...
Current development ('modernisation' phase) of the '''Boeing 777 Seattle's EFB''' is going on nicely; the code is shorter, more readable and cleaner.
I have not finished it, yet (I'd say that it's almost 50% done).

At the moment I have a single Canvas group (i.e., ''EFB_group''), with 5 children: the text-matrix (16 left lines, 16 right lines), a Title line , an Helper line and the Display. 
The ''Display'' element is then textured with all the various pages' textures, called by the page-handler (''see'' here below). 
Currently, I'm using the .jpg textures which I had previously generated through Photoshop; in the future they might be replaced by .svg files, depending from actual interactive use of some graphical objects (a few EFB pages do need interaction with graphical parts). Besides - if i'm not wrong - I've read somewhere on the FGWiki that gradients are not handled by the SVG parser...and I do like to use some gradients effects (antialiasing and such) to achieve a sort of realism on the displays.

that's the current status of the new 777 ''Seattle'''s EFB: it's still far from being perfect, but - as a newbie - I'm quite satisfied for the moment: I need to finish the first version fairly soon, because my to-do-list is long (I have to re-model all the aircraft fuselage [original model has wrong measures, ''sigh!''], produce better gears and flight-control surfaces model & animations in Blender, and then to produce a new Paint-Kit in Photoshop; then all 3D models optimizations...and so forth; of course, we also have to take care of CDU, which will interface with the EFB. So, the job is still very, very long...

The current EFB code is heavily focused on rendering raster images, which can be retained obviously, but in FG, we have additional means to render airport information that is 100% in sync with the FG side of things (navdb). 
 
For instance, we are going to "port" the airport-selection dialog to move rendering of airports/runways/taxiways/parking spots into dedicated MapStructure layers that can be properly styled and customized: [[Canvas_MapStructure#Porting_the_airports.xml_dialog]] 
 
[[File:Airport-selection-dialog.png|250px]] 
 
As you can probably tell, these kinds of layers would be very useful for any kind of EFB related application. 
 
As long as the underlying design for a "page"-based MFD framework is sufficiently generic, we can easily replace/augment raster images and procedurally created charts - we could even use the built-in support for fetching via HTTP to download images on-line. In fact, we could then even extend Canvas to directly support rendering PDFs (OSG supports this out-of-the-box), this would make many steps unnecessary, because we could directly access [http://airnav.com http://airnav.com] without having to download/convert/ship any imagery. The code required to pull this off would be very compact in comparison.

Learn more at [[Canvas EFB Framework]] or follow the [http://forum.flightgear.org/viewtopic.php?f=71&t=23204 forum discussion]...

{{Newsletter-article-start|Towards an Aircraft-agnostic MFD Framework|By [[User:Hooray|Hooray]]}}
Given the recent trend of having several MFD-related efforts without any kind of collaboration/code reuse going on here among our contributors (PFD, ND, Avidyne Entegra R9, EFB), I have started prototyping a generic MFD framework that is purely XML-based, inspired by discussions we've had over the last couple of weeks, and lessons learnt from the missions subsystem.

It is intended to:
* support multiple independent instances
* be totally aircraft agnostic
* support a pure dialog-driven mode
* support skinning/theming

This is supposed to support modeling complex avionics like a PFD, ND, EFB, CDU etc - and, eventually, also the Avidyne Entegra R9. It's currently just a prototype, but it gets away with very little code and we really only need a few more "skins" for common avionics. I am willing to extend this over time and help maintain it if people can agree to use something like this. It should be straightforward to allow such "MFDs" to be reloaded from disk at run-time, i.e. for more rapid prototyping.

{{Note|This is work in progress - the idea is to identify required building blocks to easily specify most MFD functionality in a generic fashion, without requiring a ton of custom Nasal code and without being specific to a single type of MFD. The whole concept is based on [[FlightGear_Missions_and_Adventures#XML_Extension_Framework]], i.e. providing a Nasal-space mechanism to expose and re-define building blocks to XML space.

The Nasal/Canvas data structures will be transparently created and compiled for each MFD. Each MFD consists of an arbitrary number of buttons, modes and pages. Each MFD can be instantiated multiple times, and each MFD is designed to be aircraft/instrument agnostic, i.e. also works just in a conventional Canvas dialog. Buttons can trigger and switch between modes, and modes may have pages (conventionally implemented through a single SVG file). Each page consists of an arbitrary number of page elements, which can in turn be animated/updated via listeners and timers. Should look at existing displays, especially the [[NavDisplay]] and the update() method in navdisplay.mfd, but the most complete test-case would probably be the [[Avidyne Entegra R9]] }}

<gallery mode=packed>
Gpsmap196-canvas-panel-page.png|F-JJTH has updated the SVG file implementing the panel page for the [[Garmin GPSMap 196]].
Canvas-mfd-framework-prototyping.png|This is an adapted version of the [[Garmin GPSMap 196]] that is currently being developed by F-JJTH. Here, the whole instrument is entirely set up in XML space, including buttons/event handling, but also the embedded canvas region that serves as the 'screen'. The idea is to allow arbitrary MFDs to be specified in an aircraft-agnostic fashion, including displays like a PFD, [[NavDisplay]] or EFB. For details, please see [[Canvas Glass Cockpit Efforts]].
Canvas-mfd-framework-prototyping-with-mapstructure.png|This demonstrates how a purely XML-based MFD framework can instantiate dynamic [[MapStructure]] layers - none of this involves any [[Nasal]] coding now, it's just an XML file - to learn more, see [[Canvas Glass Cockpit Efforts]].
Canvas-mfd-framework-prototyping-with-mapstructure-with-kln89-skin.png|This screen shot shows the texture of the hard-coded KLN89 instrument used as a skin/theme for the MFD instrument, with a MapStructure-powered map shown.
</gallery>

{{Newsletter-article-start|Canvas System|By [[User:Hooray|Hooray]]}}
The upcoming FlightGear version (3.2) will contain a canvas-based map dialog, including a modular "plugin" system for creating custom map layers and charts with roughly ~50 lines of code, most of it boilerplate. This is entirely XML/Nasal based (scripted) - symbols can be pretty much anything, raster or vector images (png or svg), but even animated. Styling can be customized, too.

For more info, I suggest to check out: [[MapStructure#Porting the map dialog]]

<gallery mode=packed>
MapStructureDialog.png|You can basically create arbitrary layers, even for custom objects/positions
Map-canvas-chain-home-editor.png|The same method can be used for creating a "live" radar display
MapStructure-TFC-Troubleshooting.png|
Map-canvas-dialog-storms-overlay.png|But maps and layers can be fairly sophisticated, too - all 100% scripted
</gallery>

As long as you use the MapStructure framework, all layers can be easily used in dialogs AND instruments Coding-wise, there isn't too much involved these days, all the details are covered in the MapStructure article.

{{Newsletter-article-start|Damage and disintegration|By [[User:Algernon|Algernon]]|FlightGear addons and mods}}
{{#ev:youtube|OpwNaoO3xMQ|200|right|Tomaskom's V-1 used in anger over London}}
{{#ev:youtube|H4XDuLo35ks|200|right|Victor V2.0 damage script causing a catastrophic failure and fire}}
{{#ev:youtube|uLojBI7ezdM|200|right|L-159 disintegration}}
The development team at FGUK have been experimenting with modelling aircraft damage in a number of different ways. First of all, Tomaskom has used the particle system carefully to produce visually impressive fireballs and smoke columns with very little FPS impact. First seen in his V-1, we hope to adapt this to simulate realistic fireballs for ground impacts (where appropriate). For the moment, it explodes with the full force of a V-1's explosive payload. On the right is a video excerpt from the #FlightNight which Tom organised to debut the V-1, where we all had '''way''' too much fun bombing London. As you can see, the smoke is visible from quite a long way away from the impact, and despite two fires burning with huge smoke columns, and over ten multiplayer aircraft within model range, the frame rates are still more than acceptable. StuartC has already integrated the explosion and fireball into several development aircraft, and we expect eventually to combine it with the disintegration code and make the size of the explosion dependent on fuel load etc.

In a separate development, Algernon's work on the Victor V2.0(YASim) now includes modelled damage, a collection of Nasal scripts, some modified from existing FlightGear staples, which detects irregularities such as component failures, birdstrikes and combat weapon damage and adversely affects system performance and reliability accordingly. Unserviceability often follows, using the existing FlightGear failures system, and compatibility will be maintained as the failures system is improved. The damage script also calculates probabilites for chain reaction damage - for instance, an explosion or serious fire in one Victor engine will usually have an effect on the other. In extreme circumstances, an explosion will trigger further explosions and destroy the aircraft. The second video on the right shows a serious induced explosion on the Victor's number one engine at night. Some fine-tuning of the Rembrandt light has been carried out since this video was shot, so apologies for the visible cut-off.

Finally, and most spectacularly, Tomaskom has demonstrated the disintegration capabilities of his L-159, which is under development. Hopefully, he will explain all here before publication date.

{{Newsletter-article-start|Scenesetter|By [[User:Algernon|Algernon]]}}
Scenesetter is a piece of code by Algernon, very early in development but already quite effective, which can effect changes to the time and weather from an AI scenario synchronously with other MP players. A crude proof of concept was used in the recent FGUK #FlightNight "British Weather", where pilots visited different airfields with various unpleasant flying conditions. Scenesetter pushes METAR strings to the FlightGear weather system based on the location of an associated Navaid, establishing a circular zone of a specified radius around it in which METAR will be changed. Start time can be specified too, either by providing a local start time or a local time offset (useful for Multiplayer use where players will not all start the AI scenario at precisely the same time).

{{Newsletter-article-start|Beechcraft Bonanza|By [[User:Flyingfisch|Flyingfisch]]|In the hangar}}
Flyingfisch is building the Beechcraft A35 Bonanza for Flightgear. Some pictures:
<gallery mode=packed>
Beech_bonanza_with_panel_lights_on.png|Panel lighting
Bonanza rbf.png|Remember to do your pre-flight check before startup!
Bonanza at sunrise.png|The Beech Bonanza at Kent State University (1G3) just before sunrise
Bonanza interior at sunrise.png|The interior of the Bonanza at sunrise.
</gallery>

{{Newsletter-article-start|Saab JA-37 Viggen|By [[User:Necolatis|Necolatis]]}}
The Swedish fighter jet [[Saab JA-37 Viggen]] has been updated, since it was included in FlightGear 3.0. More instruments, additional liveries, aerodynamic response to payload and tooltips on instruments. Option for automatic reverse thrust at touchdown, selection of HUD brightness, disabling of structural damage. HUD can now switch to imperial units and show MP and AI aircraft and closest airport. The aircraft now also has multiplayer sounds and better cockpit view helps seeing the landing strip. Support for FG 2.8 by deleting a small section in an xml file. Also worth mentioning is countless bug-fixes and improvements, e.g. better handling at high altitudes and a bug fix in the lift force formula.

[[File:Saab JA-37 Viggen Blue Peter Livery.png|Blå Petter Livery for JA-37]]

{{Newsletter-article-start|Updated P-51D now in git|By [[User:hvengel|hvengel]]}}
The new 3D exterior model for the [[North American P-51 Mustang|North American P-51D Mustang]] is now in git and under active development. It is currently in gray primer waiting for the UV map to be finalized. It is now fully integrated into the existing FDM. Extensive new animation work has been done including animated trim tabs and a fully functional canopy. Here are some screen shots taken in sim for your enjoyment.

<gallery mode=packed heights=250px>
P-51D testing it's guns before a flight..jpg|P-51D testing it's guns before a flight.
P-51D trim tab animation..jpg|P-51D trim tab animation.
</gallery>

{{Newsletter-article-start|Balancing the Boeing 747-400|By [[User:Gijs|Gijs]]}}
After he started developing the [[Boeing 747-400]] as a hobby project six years ago, Gijs finally managed to get the weight and balancing right. The center of gravity is now within 0.05% MAC (40 cm) of the published values.

Make sure to use the new Fuel and Payload dialog to fill your fuel tanks. There is a slider and button that will nicely distribute a specified amount of fuel, while making sure the CoG stays within the operational limits. Before takeoff, check the Takeoff Reference page on the CDU to find the required stab trim units (your current setting is displayed to the left of the throttle quadrant). When you set your trim properly, you can almost relax your yoke to the neutral position after rotate. There's still some FDM work left to fine-tune this.

The updated 747-400 is already available through Git and will be on the download page when FlightGear 3.2 is released.

{{Newsletter-article-start|Extra500 is updated to production status|By [[User:Evandenberg|Evandenberg]]}}
The [[Extra EA-500]] is updated and has reached "production status"! Just a short list of changes for release 1.1.0:
* Engine+fuel: realistic flame-out, fuel flow to collector compartment, anti ice influence on TOT, improved oil press and temp model 
* Aerodynamics: flap performance, elevator-30deg-flaps authority improvement 
* User interface: interactive checklists 
* Sounds: corrected sounds for test, CWS and AP disc 
* Model: added interior, yokes 
* Avionics: IFD moving map, automatic NAV tuning, automatic NAV switching, magnetic variation fixes 
* Autopilot: added OBS and fly vectors mode, significant improvement of coupled ILS performance
A more extensive list can be found in the "version" file.

This version does perform a bit better on my computer, but this has to do with improvements to FGFS, not of the aircraft model. So if your computer was struggling with the initial version, we recommend to use current FlightGear git/nightly builds or wait until 3.2 comes out!

Please checkout the [[Extra EA-500|Extra500 wiki]] for download instructions and lots of more info.

<gallery mode=packed heights=250px>
File:Extra500 flightgear1.png|Extra500 flying in clouds
Extra500canvas.png|Work has begun to analyze, refactor and generalize useful parts of the [[Avidyne Entegra R9]] to help reuse some code in similar MFD efforts, like the [[Garmin GPSMap 196]] or [[Canvas EFB Framework]]
</gallery>

{{Newsletter-article-start|USA state capital buildings|By [[User:Jonbourg|Jonbourg]]|Scenery corner}}
There is a project to add all the USA state capital buildings into FG. It is discussed in [http://forum.flightgear.org/viewtopic.php?f=5&t=22715&sid=ea847909bde2e1f8ffe5b94bcc673f4f this scenery forum thread]. There is also a wiki page: [[State Capitol Buildings in the United States]]. So far, Idaho, Louisiana & Nebraska have been completed. Hawaii and New York are currently in progress. Please feel free to join in with any other state that has not been done yet. Just let us know through the forum and we will add it to the in progress list.

{{Newsletter-article-start|LIPY, a scenery conversion from MSFS|By [[User:bigstones|bigstones]]}}
This month saw the [http://forum.flightgear.org/viewtopic.php?f=5&t=22623 second "preview" release] of the conversion of a scenery for MS Flight Simulator, [[Falconara Airport]] (ICAO code: LIPY), a small Italian international airport halfway down the Adriatic coast. The original author granted the permission to the conversion and even allowed for it to be included in the FlightGear official [[World Scenery]], at least the GPL compatible parts. This is not a huge limitation though, because most of the material was created from scratch, included pictures taken on purpose at the real airport, with the authorities' collaboration. Copyrighted aerial imagery only include the (unsuable) photoreal ground and some roofs.

[[File:LIPY structures landscape.jpg|650px|right]]
The conversion was made with [[ModelConverterX]], which makes the job partially easier than by [[Howto:Convert objects from X-Plane|the Blender method]], yet it's still needing fixes because of some misunderstandings with the coordinates axes. The author of the tool, though, seems not very concerned and anyway, it's so rare to have a freeware scenery author allow conversions, that the usefulness of this tool would be greatly reduced anyhow, especially if you plan to upload the models to the [[FlightGear Scenery Database]].

The conversion itself, moreover, sure is not the matter of a button press. MSFS scenery are often packed and "compiled" in *.BGL files such that independent, far objects with the same materials and same LOD level (Level Of Detail) are bound together. This is clearly against FG's way, in which each new scenery generation could change the relative heights, and however MSFS airports are flat, while in FG they're all sloped. A similar thing happens with the texture maps. This basically means that you'll have to join all these objects and split them again based on the model they belong to (e.g. tower, terminal, hangars...)

Another issue with textures is that in FG it's good practice - recommended if not mandatory - to have 2 separate texture maps for the same object, if some parts are translucent. This means that without rebuilding all the texture maps [http://forum.flightgear.org/viewtopic.php?f=5&t=22707 you'll likely get artifacts]. Then, you'd have to add the Rembrandt lights if you want, and also the lightmaps (MSFS uses night textures, but Gimp can easily convert them). This whole experience can be summed up in the following quote:

{{cquote|I really wanted to have this scenery in FG because it's my home base, and seeing it ready and so well done just made me want it. However, even if still easier than making it from scratch (even if reusing the textures), I'd have to think well if I had to do this again.|bigstones, maintainer of the conversion}}

{{Newsletter-article-start|Reshaping Leipzig/Halle Airport|By [[User:August|August]]}}
[[File:2014 new-layout-EDDP 05.jpg|650px|right]]
In FlightGear Germany's second largest cargo airport [[EDDP]] is well known as a detailed model accessible for everybody via [[TerraSync]]. Until 2013 it was famous for its regular ATC-events. It has been updated several times, at least 2012 by users D-STHO and August. When FlightGear 3.0 was published the airport layout changed from the old 810-standard to the new 850-standard. But the update (based on a taxiway layout modelled for X-Plane) turned out to be very imperfect. Many aprons and taxiways did not exist, dimensions did not appear to be correct and many new facilities which had been added at the real-world airport had not been taken into account. So maintainer August decided to redesign the whole airport from the scratch using [[WorldEditor]].
Pilots and developers are now invited to test the new airport model which includes further improvements like predefined STAR-, -SID and Transition procedures and hundreds of replaced Static- and Shared Models. The project will be published on TerraSync as soon as all defects are discovered remedied.

Developer Version:
'''git clone''' [https://gitorious.org/eddp-custom-scenery/eddp-custom-scenery/ https://gitorious.org/eddp-custom-scenery/eddp-custom-scenery/]

Feedback is welcome at [[User talk:August|August's wiki page]].
<gallery mode=packed>
2014 new-layout-EDDP 04.jpg|Taxiway T - new ground textures
2014 new-layout-EDDP 01.jpg|Runway 26L with DHL-area
2014 new-layout-EDDP 02.jpg|Apron 4
</gallery>

{{Newsletter-article-start|An updated Weather article|By [[User:bigstones|bigstones]]|Wiki updates}}
The [[Weather]] wiki article went through a wide extension. Although Advanced Weather was released quite a while ago, its usage has never been explained in the wiki, and some thorough instructions were available only in a readme in the "docs" folder of the base package which is not commonly explored by users, while the wiki article [[Advanced weather]] is more about the project than the usage.

AW's advanced configuration is known to be not easy. So, if you always only used the weather selection menu and want to know more, or want to understand what the options actually do and how you can combine them, the [[Weather]] article has now been updated with some hints and basic notions extracted from experience and the original documentation, and quality checked by the author of the AW weather engine.

{{Newsletter-article-start|Translators required|}}
{|
|[[File:en.gif]]
|The FlightGear Wiki still needs help for translating it into various languages. If you are interested in making the FlightGear Wiki multi-language then start at [[Help:Translate]].
|-
|[[File:de.gif]]
|Das FlightGear Wiki benötigt immer noch Hilfe bei der Übersetzung in verschiedene Sprachen. Wenn Du Interesse daran hast, das FlightGear Wiki Mehrsprachig zu machen, dann fang doch mit [[:de:Help:Übersetzen|Help:Übersetzen]] an.
|-
|[[File:nl.gif]]
|De FlightGear Wiki kan nog steed hulp gebruiken bij het vertalen van artikelen. Als je interesse hebt om de wiki meertalig te maken, raden we je aan om een kijkje te nemen bij [[:nl:Help:Vertalen|Help:Vertalen]].
|-
|[[File:es.gif]]
|La FlightGear wiki todavía necesita ayuda para traducirla a varios lenguajes. Si estás interesado en hacer la FlightGear wiki multilingüe, entonces comienza en [[:es:Help:Traducir|Help:Traducir]].
|}

{{Newsletter-article-start|Call for volunteers||And finally...}}
* The [[TerraGear]] maintainers are looking for volunteers to help with development on the next world scenery project. If you've ever wondered how a full 3D model of earth can be generated from raw data, now is your chance. See the plan at [[TerraGear roadmap]].

[[Category:FlightGear Newsletter|2014 06]]
[[Category:Changes after 3.00]]

Changelog 3.2

2014-06-30T12:00:42Z

TheTom: Nasal core changes

{{draft|changelog|This changelog is currently being written for the FlightGear 3.2 release. To see what is being worked on, check out [[Changelog 3.2]].
Feel free to help! If you are aware of any FlightGear related changes, please add them to the changelog. It's a good idea to check [[:Category:Changes_after_3.00|the newsletters since the last release]], and the git commit history.
To view the changelog for the most recent release, please see [[Changelog 3.0]].
We also encourage people to help by translating the changelog and appreciate all contributions, however please keep in mind that this changelog is not yet final!

}}

==Upcoming FlightGear Changelog==



=== Breaking Changes ===

=== Major enhancements in this release ===

'''Surface Light Effects & OpenSceneGraph 3.2'''

Stuart committed a change that brings surface lights, including VASI/PAPI/taxi/runway etc. into the xml-defined Effects framework. Kudos to Tim Moore for his original Effects work - it made it very straightforward to enhance with support for point sprites and a custom texture generator required.

The relevant effect is data/Effects/surface-lights.eff. It should allow development of ALS and Rembrandt variants.

Stuart also replaced some OSG color/normal binding calls that were removed in OSG3.2.0, apparently because they were slow. So, if your
build fails, please check you've got a recent OSG build installed.

'''Core'''
* [[Reset & re-init]] is merged and now enabled
* A segfault related to scripted Nasal fgcommands (like used in joystick and other bindings) has been fixed {{Issue|1397}}
* yasim versioning support for maintenance fixes (TorstenD)
* FLITE TTS support
* Windows dependencies have been updated
* improved projection handling for the integrated [[Map]] dialog, implemented by Gijs[https://gitorious.org/fg/flightgear/commit/3f433e2c35ef533a847138e6ae10a5cb398323d7#comment_107170]

'''Aircraft Modeling'''
* galvedro's work: [[A Failure Management Framework for FlightGear]]
* extra 500
* Tu-154B2 version 3.1
* additional aircraft have started adopting Gijs' [[NavDisplay]]

'''JSBSim'''
* ground effects (see newsletter 02/2014)

'''Atmospheric Light Scattering'''

Atmospheric Light Scattering (ALS) is one of FGs three rendering frameworks, with the aim of providing an integrated simulation of the interaction between weather, light and the environment.

Additions to ALS in version 3.2 include:

* an experimental framework to render cloud shadows on the ground (requires Advanced Weather)
* a substantial extension of cloud layer visibility using impostor techniques to 150 km
* a new agriculture effect allowing to render fields without tiling artifacts
* a new forest effect to simulate managed forest, varying tree size by patch
* sparkle and fog effect on runway lights
* much improved visual appearance of rock faces

'''Environment Rendering'''

* EarthView, a simple orbital rendering engine based on projecting a textured sphere into the scene. By default, EarthView uses low resolution textures, however using hires textures e.g. from the NASA [http://visibleearth.nasa.gov/ Visible Earth] project very realistic results from altitudes above 100 km can be achieved.

* new deciduous and needle tree textures with much improved visuals

* new regional texture definitions for Ireland, Alaska/Northwest territories and US Southwest

'''Performance'''
* F-JJTH and Stuart have started working on using osg::Simplifier [https://gitorious.org/fg/simgear/commit/3429e0072103a8c90d8e456f1f6b711099851225]: http://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/CAP3ntysifK34TxANKUj1s4Of_dJRg7dvJ74Gbko4zXVFHdV-YQ%40mail.gmail.com/#msg32016452

'''Misc/Uncategorized'''
* AIModels use PagedLOD
* Optimise NavCache airport query
* osg::Switch for masking scenery rendering
* Torsten's metar work, newradio, mongoose httpd
* HTTP: improve handling of connection errors
* [[FGCamera]] (external addon, not yet reviewed/committed as of 03/2014)
* Windows installer has been reworked
* Windows installer creates 3 news directories pre-configured in FGRun:
** {user}\Documents\FlightGear\Aircraft
** {user}\Documents\FlightGear\TerraSync
** {user}\Documents\FlightGear\Custom Scenery

''' Usability '''
* Windows users are now able to use scrollwheel in dialog

''' Internationalization '''

''' Scenery '''

'''Canvas System'''

FlightGear's fully scriptable 2D rendering system now includes improved APIs for creating maps and navigation displays amongst many other improvements. People no longer need to have programming experience to add a working ND to their aircraft, it can now be all done by copying and pasting 30 lines of text and customizing a few properties. The so called MapStructure back-end handles efficient updating of all ND layers transparently. Also, maps can now be mostly customized, including custom styling (colors, fonts, symbols etc).

* Tom has pushed an update to git (simgear) which removes a lot of unneeded OpenGL state changes for Canvas paths. Depending on the GPU/driver this can lead to quite a noticeable performance improvement. For example, he was able to get from ~120ms down to ~45ms [http://forum.flightgear.org/viewtopic.php?f=71&t=16984&p=204730#p204730].

* Gijs is currently working on additional projections as part of {{Issue|550}}
* The [[MapStructure]] back-end used by the [[NavDisplay]] now supports symbol instancing, so that performance is improved
* MapStructure-based layers can now be customized and styled
* Tom added support for button/modifiers (mouse handling) [http://wiki.flightgear.org/index.php?title=Canvas_Event_Handling&curid=10777&diff=68569&oldid=68422]
* CanvasImage now supports the ''http://'' protocol for dynamically retrieving raster images. See the renamed [[Canvas_Image#src|src attribute]] (''file'' is now deprecated).
* As part of the ongoing effort on [[Unifying the 2D rendering backend via canvas]], we have started re-implementing the integrated [[Map]] dialog using Nasal & Canvas instead of C++ {{Progressbar|80}}
* Custom event handlers can now be registered.
* Canvas Layout Engine
* Canvas-based dialog for downloading aircraft [[Aircraft Center]]
[[File:Aircraft-center-prototype.png|400px|thumb|Canvas dialog showing the prototype for an [[Aircraft Center]] for directly installing/managing aircraft from within FlightGear, an upcoming feature scheduled for FlightGear 3.2, currently being developed by TheTom and Zakalawe]]

'''Nasal Scripting'''

* getprop()/setprop() arguments (those that form a path) can now be numeric to specify a index, so:
<syntaxhighlight lang="nasal">
getprop("canvas/by-index", "texture", 1, "name");
</syntaxhighlight>
: is now the same as:
<syntaxhighlight lang="nasal">
getprop("canvas/by-index/texture[1]/name");
</syntaxhighlight>
: (see [https://gitorious.org/fg/flightgear/commit/5eee5e42ae4f5cf56283b3bf5a3be46efc2b51c4 merge request 54] and [https://gitorious.org/fg/flightgear/commit/34ed79e5f88ffdfc5e651a1fe3e639cb8f4d3353 actual commit])
* A new fully-interactive Nasal GUI console based on [[Canvas]] has been added: [[Interactive Nasal Console]]
* the hard-coded '''flight path history''' subsystem which samples aircraft position, which was previously only accessible to C++ code, has now been exposed to scripting space by Tom so that people can easily access the system and reuse the data for their own purpoes (e.g. for creating an instructor console). The first use-case will involve the new [[Canvas]] based [[Map]] dialog which will be 100% scripted by then.
: Usage:
<syntaxhighlight lang="nasal">
var hist = aircraft.history(); debug.dump(hist.pathForHistory(50));
</syntaxhighlight>
* cppbind: Nasal ghosts can now support arbitrary setters/getters for when members are not mapped to a C++ member/method.
* Language enhancements
** Bitwise operators (|, &, ^, ~, |=, &=, ^=)
** Support for octal, decimal and hexadecimal numbers in literals as well as in strings

'''Documentation'''

'''Highlighted new and improved aircraft'''

Tuned autopilot and improved instrument stack for the Cessna337G Skymaster.

'''Other'''

'''Bug fixes'''

* See [http://code.google.com/p/flightgear-bugs/issues/list?can=1&q=Milestone%3D3.2 our bugtracker] for an extensive, yet incomplete, list of the bugs fixed in this release.

[[Category:FlightGear changelogs]]

FlightGear Newsletter June 2014

2014-06-30T07:40:24Z

TheTom:

{{Newsletter-header|June 2014}}
<div style="border-bottom:3px double #BBB;">
{| width="100%" |
| valign="top" width="33%" |
{{Newsletter-cover-header|Development news}} 
{{Newsletter-cover-item|FlightGear 3.2 - Feature Freeze}} 
{{Newsletter-cover-item|Canvas GUI: MessageBox Support}} 
{{Newsletter-cover-item|Logo proposal}} 
{{Newsletter-cover-header|Addons and mods}} 
{{Newsletter-cover-item|Damage and disintegration}} 
{{Newsletter-cover-item|Scenesetter}}
| valign="top" width="33%" |
{{Newsletter-cover-header|In the hangar}} 
{{Newsletter-cover-item|Beechcraft Bonanza}} 
{{Newsletter-cover-item|Saab JA-37 Viggen}} 
{{Newsletter-cover-item|Updated P-51D now in git}} 
{{Newsletter-cover-item|Balancing the Boeing 747-400}} 
{{Newsletter-cover-item|Extra500 is updated to production status}}
| valign="top" width="33%" |
{{Newsletter-cover-header|Scenery corner}} 
{{Newsletter-cover-item|USA state capital buildings}} 
{{Newsletter-cover-item|LIPY, a scenery conversion from MSFS}} 
{{Newsletter-cover-item|Reshaping Leipzig/Halle Airport}} 
{{Newsletter-cover-header|Wiki updates}} 
{{Newsletter-cover-item|An updated Weather article}}
|}
</div>

{{Template:Newsletter-article-start|{{{1|FlightGear 3.2 - Feature Freeze}}}|By [[User:t3r|TorstenD]]|Development news}}
On June 17, we entered our scheduled feature freeze state for the next release. Please use the remaining weeks to improve the existing features, harden and cleanup the code, edit the [[Next Changelog|ChangeLog]], improve the Manual, document the undocumented etc. etc. The release branches will be created on July 17th to have the release ready by Aug. 17th.

{{Template:Newsletter-article-start|{{{1|Canvas GUI: MessageBox Support}}}|By [[User:TheTom|TheTom]]}}
Thanks to Tom's and James' recent work on the upcoming [[Aircraft Center]] for downloading and switching between aircraft without having to exit FlightGear, beginning with FlightGear 3.2, FlightGear's [[Canvas]]-based GUI will contain support for so called [[Canvas MessageBox|Message Boxes]]:
{|
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo information.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.information("Success", "The operation has successfully completed.");
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo question.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.question(
"Do you want it?",
"The question is: Do you want to get a real question?.",
func(sel)
{
if( sel == canvas.MessageBox.Yes )
print("I only know that the answer is 42.");
else
print("Ok, I will not give you a real question.");
}
);
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo warning dont-show-again.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.warning(
"Warning...",
"Have you read this warning? If you want it will not be shown again.",
func(sel)
{
if( sel != canvas.MessageBox.Ok )
return;

print("You have been warned. Let the games begin...");
},
canvas.MessageBox.Ok
| canvas.MessageBox.Cancel
| canvas.MessageBox.DontShowAgain
);
</syntaxhighlight>
|}

{{Newsletter-article-start|Logo proposal|By [[User:Aepcam|Aepcam]]}}
This is a new logo badge concept proposal for FlightGear designed by Michat.

[[File:Fglogo1.png]]
[[File:Fglogowiki.png]]
[[File:Fglogoforum.png]]

{{Newsletter-article-start|MapStructure stress-testing|By [[User:Hooray|Hooray]]}}
[[File:Map-canvas-mapstructure-performance.png|thumb|stress-testing [[MapStructure]] using the ufo @ KSFO circling at 2000 kts in a climb, see [http://forum.flightgear.org/viewtopic.php?f=71&t=21509&p=211611#p211611] ]]

{{cquote
|<nowiki>Now that Hyde has committed Philosopher's latest changes, I'd be interested in getting some more feedback on performance.</nowiki> <nowiki>
Here, I am using the ufo @ksfo circling in a shuttle climb at >= 2000 kts GS and getting roughly 30 fps and 40-60 ms.</nowiki>
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=211611#p211611
|title=<nowiki>Re: NavDisplay & MapStructure discussion (previously via PM)</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Tue Jun 03</nowiki>
}}
}}

== Creating Canvas GUI Dialogs ==
'''Targeted FlightGear versions: >= 3.20'''
[[File:Canvas GUI Demo Dialog.png|400px|thumb|Screen shot showing a simple [[Canvas GUI]] dialog with a handful of [[Canvas Widgets|Button Widgets]].]]
== Editing Translations/en/menu.xml ==
Navigate to the sub-menu where you'd like to add your new dialog, e.g. "Equipment" in this case, and then add a key:
<syntaxhighlight lang="xml">
<equipment>Equipment</equipment>
<canvas-demo-dialog>Canvas Demo Dialog</canvas-demo-dialog>
</syntaxhighlight>

== Editing gui/menubar.xml ==
Next, open $FG_ROOT/gui/menubar.xml and navigate to the corresponding sub-menu and add a new item/binding to load your dialog:
<syntaxhighlight lang="xml">
<item>
<name>canvas-demo-dialog</name>
<binding>
<command>nasal</command>
<script>
canvas.loadDialog("CanvasDemo");
</script>
</binding>
</item>
</syntaxhighlight>

== Creating the actual dialog file ==
{{Note|These dialog files can be edited at run-time and simply closed/re-opened, because the Canvas system will reload them from disk whenever the menu binding is triggered. So this is very convenient for quickly developing and testing your dialogs.}}
Next, open/create $FG_ROOT/Nasal/canvas/gui/dialogs/CanvasDemo.nas and add some boilerplate code:
<syntaxhighlight lang="nasal">
var DemoDialog = {
new: func
{
var m = {
parents: [DemoDialog],
_dlg: canvas.Window.new([400,300], "dialog")
.set("title", "Demo Dialog")
.set("resize", 1),
_active_button: nil
};

m._dlg.getCanvas(1)
.set("background", canvas.style.getColor("bg_color"));
m._root = m._dlg.getCanvas().createGroup();

var vbox = VBoxLayout.new();
m._dlg.setLayout(vbox);

return m;
},
};

var demo = DemoDialog.new();
</syntaxhighlight>

Finally, start FlightGear and open your new dialog

== Adding Widgets ==
== Using Layouts ==

== Using Styling ==

=== 777 EFB Prototype by I-NEMO ===
[[File:777-EFB-MAIN.png|thumb|777-200ER EFB [http://forum.flightgear.org/viewtopic.php?f=71&t=23196]]]
[[File:777-EFB-AIRPORT-SEARCH.png|thumb|777-200 EFB AIRPORT SEARCH, see [http://forum.flightgear.org/viewtopic.php?f=71&t=23196&p=211410#p211410]]]

I-NEMO has started porting his 777/EFB prototype to [[Canvas]]

{{cquote
|<nowiki>As I wrote several times, I finally decided to put hands on the EFB (Reason: No one ever took care of developing an EFB for the 777; a 'working' EFB, though) with two (2) main goals in mind:</nowiki> <nowiki>
</nowiki> <nowiki>
1) to do something to compensate for the lacking of an EFB inside the Seattle.</nowiki> <nowiki>
2) to actually try (I repeat it: 'try') to learn some first essentials of nasal.</nowiki> <nowiki>
</nowiki>
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=211550#p211550
|title=<nowiki>Re: 777 EFB status & plans ?</nowiki>
|author=<nowiki>I-NEMO</nowiki>
|date=<nowiki>Mon Jun 02</nowiki>
}}
}}

{{cquote
|<nowiki> this Seattle EFB is just a 'rude' one: with this term, I mean (as a word's pun) 'unpolite'. I'm perfectly aware that the coding is horrible, clumsy, repetitive, silly and very, very far from what it should be. </nowiki> <nowiki>
My first aim was simply to have a somehow 'working' EFB inside the Seattle's Cockpit.</nowiki> <nowiki>
</nowiki> <nowiki>
My second aim was to use EFB.nas as a starting playground for a newbie as I am on 'nasal'. </nowiki>
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=211550#p211550
|title=<nowiki>Re: 777 EFB status & plans ?</nowiki>
|author=<nowiki>I-NEMO</nowiki>
|date=<nowiki>Mon Jun 02</nowiki>
}}
}}

{{cquote
|<nowiki>I do not pretend that current 777's EFB.nas is a piece of nice software; but - to my initial purpose - it works. Not completely, not nicely, not properly...but it's a starting point. At least, it works...</nowiki>
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=211550#p211550
|title=<nowiki>Re: 777 EFB status & plans ?</nowiki>
|author=<nowiki>I-NEMO</nowiki>
|date=<nowiki>Mon Jun 02</nowiki>
}}
}}

{{FGCquote
|Current development ('modernisation' phase) of the '''Boeing 777 Seattle's EFB''' is going on nicely; the code is shorter, more readable and cleaner. 
I have not finished it, yet (I'd say that it's almost 50% done).
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=213104#p213104
|title=<nowiki>Re: 777 EFB: initial feedback</nowiki>
|author=<nowiki>I-NEMO</nowiki>
|date=<nowiki>Sat Jun 21</nowiki>
}}
}}

{{FGCquote
|At the moment I have a single Canvas group (i.e., ''EFB_group''), with 5 children: the text-matrix (16 left lines, 16 right lines), a Title line , an Helper line and the Display. 
The ''Display'' element is then textured with all the various pages' textures, called by the page-handler (''see'' here below). 
Currently, I'm using the .jpg textures which I had previously generated through Photoshop; in the future they might be replaced by .svg files, depending from actual interactive use of some graphical objects (a few EFB pages do need interaction with graphical parts). Besides - if i'm not wrong - I've read somewhere on the FGWiki that gradients are not handled by the SVG parser...and I do like to use some gradients effects (antialiasing and such) to achieve a sort of realism on the displays.
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=213104#p213104
|title=<nowiki>Re: 777 EFB: initial feedback</nowiki>
|author=<nowiki>I-NEMO</nowiki>
|date=<nowiki>Sat Jun 21</nowiki>
}}
}}

{{FGCquote
|that's the current status of the new 777 ''Seattle'''s EFB: it's still far from being perfect, but - as a newbie - I'm quite satisfied for the moment: I need to finish the first version fairly soon, because my to-do-list is long (I have to re-model all the aircraft fuselage [original model has wrong measures, ''sigh!''], produce better gears and flight-control surfaces model & animations in Blender, and then to produce a new Paint-Kit in Photoshop; then all 3D models optimizations...and so forth; of course, we also have to take care of CDU, which will interface with the EFB. So, the job is still very, very long...
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=213104#p213104
|title=<nowiki>Re: 777 EFB: initial feedback</nowiki>
|author=<nowiki>I-NEMO</nowiki>
|date=<nowiki>Sat Jun 21</nowiki>
}}
}}

{{FGCquote
|The current EFB code is heavily focused on rendering raster images, which can be retained obviously, but in FG, we have additional means to render airport information that is 100% in sync with the FG side of things (navdb). 
 
For instance, we are going to "port" the airport-selection dialog to move rendering of airports/runways/taxiways/parking spots into dedicated MapStructure layers that can be properly styled and customized: [[Canvas_MapStructure#Porting_the_airports.xml_dialog]] 
 
[[File:Airport-selection-dialog.png|250px]] 
 
As you can probably tell, these kinds of layers would be very useful for any kind of EFB related application. 
 
As long as the underlying design for a "page"-based MFD framework is sufficiently generic, we can easily replace/augment raster images and procedurally created charts - we could even use the built-in support for fetching via HTTP to download images on-line. In fact, we could then even extend Canvas to directly support rendering PDFs (OSG supports this out-of-the-box), this would make many steps unnecessary, because we could directly access [http://airnav.com http://airnav.com] without having to download/convert/ship any imagery. The code required to pull this off would be very compact in comparison.
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=213084#p213084
|title=<nowiki>Re: 777 EFB: initial feedback</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Sat Jun 21</nowiki>
}}
}}

Learn more at [[Canvas EFB Framework]] ...

=== Canvas Garmin GPSMap196 Updates ===

[[File:Gpsmap196-canvas-panel-page.png|thumb|F-JJTH has updated the SVG file implementing the panel page for the [[Garmin GPSMap 196]]]]

=== Towards an Aircraft-agnostic MFD Framework ===

[[File:Canvas-mfd-framework-prototyping.png|thumb|This is an adapted version of the [[Garmin GPSMap 196]] that is currently being developed by F-JJTH. Here, the whole instrument is entirely set up in XML space, including buttons/event handling, but also the embedded canvas region that serves as the 'screen'. The idea is to allow arbitrary MFDs to be specified in an aircraft-agnostic fashion, including displays like a PFD, [[NavDisplay]] or EFB. For details, please see [[Canvas Glass Cockpit Efforts]].]]

[[File:Canvas-mfd-framework-prototyping-with-mapstructure.png|400px|thumb|This demonstrates how a purely XML-based MFD framework can instantiate dynamic [[MapStructure]] layers - none of this involves any [[Nasal]] coding now, it's just an XML file - to learn more, see [[Canvas Glass Cockpit Efforts]].]]

[[File:Canvas-mfd-framework-prototyping-with-mapstructure-with-kln89-skin.png|400px|thumb|This screen shot shows the texture of the hard-coded KLN89 instrument used as a skin/theme for the MFD instrument, with a MapStructure-powered map shown.]]

=== Canvas System ===
{{FGCquote
|The upcoming FlightGear version (3.2) will contain a canvas-based map dialog, including a modular "plugin" system for creating custom map layers and charts with roughly ~50 lines of code, most of it boilerplate. This is entirely XML/Nasal based (scripted) - symbols can be pretty much anything, raster or vector images (png or svg), but even animated. Styling can be customized, too. For more info, I suggest to check out: [[MapStructure#Porting_the_map_dialog|http://wiki.flightgear.org/MapStructure ... map_dialog]] [[File:MapStructureDialog.png|250px]] You can basically create arbitrary layers, even for custom objects/positions: [[File:Map-canvas-chain-home-editor.png|250px]] The same method can be used for creating a "live" radar display: [[Canvas_Radar|http://wiki.flightgear.org/Canvas_Radar]] [[File:MapStructure-TFC-Troubleshooting.png|250px]] But maps and layers can be fairly sophisticated, too - all 100% scripted: [[FlightGear_Newsletter_May_2014#A_Canvas-based_Map_dialog|http://wiki.flightgear.org/FlightGear_N ... Map_dialog]] [[File:Map-canvas-dialog-storms-overlay.png|250px]] As long as you use the MapStructure framework, all layers can be easily used in dialogs AND instruments Coding-wise, there isn't too much involved these days, all the details are covered in the MapStructure article.
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=212558#p212558
|title=<nowiki>Re: Get objects to show up on Map/Radar</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Sat Jun 14</nowiki>
}}
}}

[[File:Aircraft-center-prototype.png|500px|thumb|Canvas dialog showing the prototype for an [[Aircraft Center]] for directly installing/managing aircraft from within FlightGear, an upcoming feature scheduled for FlightGear 3.2, currently being developed by TheTom and Zakalawe]]

{{Newsletter-article-start|Damage and disintegration|By [[User:Algernon|Algernon]]|FlightGear addons and mods}}
{{#ev:youtube|OpwNaoO3xMQ|200|right|Tomaskom's V-1 used in anger over London}}
{{#ev:youtube|H4XDuLo35ks|200|right|Victor V2.0 damage script causing a catastrophic failure and fire}}
{{#ev:youtube|uLojBI7ezdM|200|right|L-159 disintegration}}
The development team at FGUK have been experimenting with modelling aircraft damage in a number of different ways. First of all, Tomaskom has used the particle system carefully to produce visually impressive fireballs and smoke columns with very little FPS impact. First seen in his V-1, we hope to adapt this to simulate realistic fireballs for ground impacts (where appropriate). For the moment, it explodes with the full force of a V-1's explosive payload. On the right is a video excerpt from the #FlightNight which Tom organised to debut the V-1, where we all had '''way''' too much fun bombing London. As you can see, the smoke is visible from quite a long way away from the impact, and despite two fires burning with huge smoke columns, and over ten multiplayer aircraft within model range, the frame rates are still more than acceptable. StuartC has already integrated the explosion and fireball into several development aircraft, and we expect eventually to combine it with the disintegration code and make the size of the explosion dependent on fuel load etc.

In a separate development, Algernon's work on the Victor V2.0(YASim) now includes modelled damage, a collection of Nasal scripts, some modified from existing FlightGear staples, which detects irregularities such as component failures, birdstrikes and combat weapon damage and adversely affects system performance and reliability accordingly. Unserviceability often follows, using the existing FlightGear failures system, and compatibility will be maintained as the failures system is improved. The damage script also calculates probabilites for chain reaction damage - for instance, an explosion or serious fire in one Victor engine will usually have an effect on the other. In extreme circumstances, an explosion will trigger further explosions and destroy the aircraft. The second video on the right shows a serious induced explosion on the Victor's number one engine at night. Some fine-tuning of the Rembrandt light has been carried out since this video was shot, so apologies for the visible cut-off.

Finally, and most spectacularly, Tomaskom has demonstrated the disintegration capabilities of his L-159, which is under development. Hopefully, he will explain all here before publication date.

{{Newsletter-article-start|Scenesetter|By [[User:Algernon|Algernon]]}}
Scenesetter is a piece of code by Algernon, very early in development but already quite effective, which can effect changes to the time and weather from an AI scenario synchronously with other MP players. A crude proof of concept was used in the recent FGUK #FlightNight "British Weather", where pilots visited different airfields with various unpleasant flying conditions. Scenesetter pushes METAR strings to the FlightGear weather system based on the location of an associated Navaid, establishing a circular zone of a specified radius around it in which METAR will be changed. Start time can be specified too, either by providing a local start time or a local time offset (useful for Multiplayer use where players will not all start the AI scenario at precisely the same time).

{{Newsletter-article-start|Beechcraft Bonanza|By [[User:Flyingfisch|Flyingfisch]]|In the hangar}}
Flyingfisch is building the Beechcraft A35 Bonanza for Flightgear. Some pictures:
<gallery mode=packed>
Beech_bonanza_with_panel_lights_on.png|Panel lighting
Bonanza rbf.png|Remember to do your pre-flight check before startup!
Bonanza at sunrise.png|The Beech Bonanza at Kent State University (1G3) just before sunrise
Bonanza interior at sunrise.png|The interior of the Bonanza at sunrise.
</gallery>

{{Newsletter-article-start|Saab JA-37 Viggen|By [[User:Necolatis|Necolatis]]}}
The Swedish fighter jet [[Saab JA-37 Viggen]] has been updated, since it was included in FlightGear 3.0. More instruments, additional liveries, aerodynamic response to payload and tooltips on instruments. Option for automatic reverse thrust at touchdown, selection of HUD brightness, disabling of structural damage. HUD can now switch to imperial units and show MP and AI aircraft and closest airport. The aircraft now also has multiplayer sounds and better cockpit view helps seeing the landing strip. Support for FG 2.8 by deleting a small section in an xml file. Also worth mentioning is countless bug-fixes and improvements, e.g. better handling at high altitudes and a bug fix in the lift force formula.

[[File:Saab JA-37 Viggen Blue Peter Livery.png|Blå Petter Livery for JA-37]]

{{Newsletter-article-start|Updated P-51D now in git|By [[User:hvengel|hvengel]]}}
The new 3D exterior model for the [[North American P-51 Mustang|North American P-51D Mustang]] is now in git and under active development. It is currently in gray primer waiting for the UV map to be finalized. It is now fully integrated into the existing FDM. Extensive new animation work has been done including animated trim tabs and a fully functional canopy. Here are some screen shots taken in sim for your enjoyment.

<gallery mode=packed heights=250px>
P-51D testing it's guns before a flight..jpg|P-51D testing it's guns before a flight.
P-51D trim tab animation..jpg|P-51D trim tab animation.
</gallery>

{{Newsletter-article-start|Balancing the Boeing 747-400|By [[User:Gijs|Gijs]]}}
After he started developing the [[Boeing 747-400]] as a hobby project six years ago, Gijs finally managed to get the weight and balancing right. The center of gravity is now within 0.05% MAC (40 cm) of the published values.

Make sure to use the new Fuel and Payload dialog to fill your fuel tanks. There is a slider and button that will nicely distribute a specified amount of fuel, while making sure the CoG stays within the operational limits. Before takeoff, check the Takeoff Reference page on the CDU to find the required stab trim units (your current setting is displayed to the left of the throttle quadrant). When you set your trim properly, you can almost relax your yoke to the neutral position after rotate. There's still some FDM work left to fine-tune this.

The updated 747-400 is already available through Git and will be on the download page when FlightGear 3.2 is released.

{{Newsletter-article-start|Extra500 is updated to production status|By [[User:Evandenberg|Evandenberg]]}}
The [[Extra EA-500]] is updated and has reached "production status"! Just a short list of changes for release 1.1.0:
* Engine+fuel: realistic flame-out, fuel flow to collector compartment, anti ice influence on TOT, improved oil press and temp model 
* Aerodynamics: flap performance, elevator-30deg-flaps authority improvement 
* User interface: interactive checklists 
* Sounds: corrected sounds for test, CWS and AP disc 
* Model: added interior, yokes 
* Avionics: IFD moving map, automatic NAV tuning, automatic NAV switching, magnetic variation fixes 
* Autopilot: added OBS and fly vectors mode, significant improvement of coupled ILS performance
A more extensive list can be found in the "version" file.

This version does perform a bit better on my computer, but this has to do with improvements to FGFS, not of the aircraft model. So if your computer was struggling with the initial version, we recommend to use current FlightGear git/nightly builds or wait until 3.2 comes out!

Please checkout the [[Extra EA-500|Extra500 wiki]] for download instructions and lots of more info.

<gallery mode=packed heights=250px>
File:Extra500 flightgear1.png|Extra500 flying in clouds
Extra500canvas.png|Work has begun to analyze, refactor and generalize useful parts of the [[Avidyne Entegra R9]] to help reuse some code in similar MFD efforts, like the [[Garmin GPSMap 196]] or [[Canvas EFB Framework]]
</gallery>

{{Newsletter-article-start|USA state capital buildings|By [[User:Jonbourg|Jonbourg]]|Scenery corner}}
There is a project to add all the USA state capital buildings into FG. It is discussed in [http://forum.flightgear.org/viewtopic.php?f=5&t=22715&sid=ea847909bde2e1f8ffe5b94bcc673f4f this scenery forum thread]. There is also a wiki page: [[State Capitol Buildings in the United States]]. So far, Idaho, Louisiana & Nebraska have been completed. Hawaii and New York are currently in progress. Please feel free to join in with any other state that has not been done yet. Just let us know through the forum and we will add it to the in progress list.

{{Newsletter-article-start|LIPY, a scenery conversion from MSFS|By [[User:bigstones|bigstones]]}}
This month saw the [http://forum.flightgear.org/viewtopic.php?f=5&t=22623 second "preview" release] of the conversion of a scenery for MS Flight Simulator, [[Falconara Airport]] (ICAO code: LIPY), a small Italian international airport halfway down the Adriatic coast. The original author granted the permission to the conversion and even allowed for it to be included in the FlightGear official [[World Scenery]], at least the GPL compatible parts. This is not a huge limitation though, because most of the material was created from scratch, included pictures taken on purpose at the real airport, with the authorities' collaboration. Copyrighted aerial imagery only include the (unsuable) photoreal ground and some roofs.

[[File:LIPY structures landscape.jpg|650px|right]]
The conversion was made with [[ModelConverterX]], which makes the job partially easier than by [[Howto:Convert objects from X-Plane|the Blender method]], yet it's still needing fixes because of some misunderstandings with the coordinates axes. The author of the tool, though, seems not very concerned and anyway, it's so rare to have a freeware scenery author allow conversions, that the usefulness of this tool would be greatly reduced anyhow, especially if you plan to upload the models to the [[FlightGear Scenery Database]].

The conversion itself, moreover, sure is not the matter of a button press. MSFS scenery are often packed and "compiled" in *.BGL files such that independent, far objects with the same materials and same LOD level (Level Of Detail) are bound together. This is clearly against FG's way, in which each new scenery generation could change the relative heights, and however MSFS airports are flat, while in FG they're all sloped. A similar thing happens with the texture maps. This basically means that you'll have to join all these objects and split them again based on the model they belong to (e.g. tower, terminal, hangars...)

Another issue with textures is that in FG it's good practice - recommended if not mandatory - to have 2 separate texture maps for the same object, if some parts are translucent. This means that without rebuilding all the texture maps [http://forum.flightgear.org/viewtopic.php?f=5&t=22707 you'll likely get artifacts]. Then, you'd have to add the Rembrandt lights if you want, and also the lightmaps (MSFS uses night textures, but Gimp can easily convert them). This whole experience can be summed up in the following quote:

{{cquote|I really wanted to have this scenery in FG because it's my home base, and seeing it ready and so well done just made me want it. However, even if still easier than making it from scratch (even if reusing the textures), I'd have to think well if I had to do this again.|bigstones, maintainer of the conversion}}

{{Newsletter-article-start|Reshaping Leipzig/Halle Airport|By [[User:August|August]]}}
[[File:2014 new-layout-EDDP 05.jpg|650px|right]]
In FlightGear Germany's second largest cargo airport [[EDDP]] is well known as a detailed model accessible for everybody via [[TerraSync]]. Until 2013 it was famous for its regular ATC-events. It has been updated several times, at least 2012 by users D-STHO and August. When FlightGear 3.0 was published the airport layout changed from the old 810-standard to the new 850-standard. But the update (based on a taxiway layout modelled for X-Plane) turned out to be very imperfect. Many aprons and taxiways did not exist, dimensions did not appear to be correct and many new facilities which had been added at the real-world airport had not been taken into account. So maintainer August decided to redesign the whole airport from the scratch using [[WorldEditor]].
Pilots and developers are now invited to test the new airport model which includes further improvements like predefined STAR-, -SID and Transition procedures and hundreds of replaced Static- and Shared Models. The project will be published on TerraSync as soon as all defects are discovered remedied.

Developer Version:
'''git clone''' [https://gitorious.org/eddp-custom-scenery/eddp-custom-scenery/ https://gitorious.org/eddp-custom-scenery/eddp-custom-scenery/]

Feedback is welcome at [[User talk:August|August's wiki page]].
<gallery mode=packed>
2014 new-layout-EDDP 04.jpg|Taxiway T - new ground textures
2014 new-layout-EDDP 01.jpg|Runway 26L with DHL-area
2014 new-layout-EDDP 02.jpg|Apron 4
</gallery>

{{Newsletter-article-start|An updated Weather article|By [[User:bigstones|bigstones]]|Wiki updates}}
The [[Weather]] wiki article went through a wide extension. Although Advanced Weather was released quite a while ago, its usage has never been explained in the wiki, and some thorough instructions were available only in a readme in the "docs" folder of the base package which is not commonly explored by users, while the wiki article [[Advanced weather]] is more about the project than the usage.

AW's advanced configuration is known to be not easy. So, if you always only used the weather selection menu and want to know more, or want to understand what the options actually do and how you can combine them, the [[Weather]] article has now been updated with some hints and basic notions extracted from experience and the original documentation, and quality checked by the author of the AW weather engine.

{{Newsletter-article-start|Translators required|}}
{|
|[[File:en.gif]]
|The FlightGear Wiki still needs help for translating it into various languages. If you are interested in making the FlightGear Wiki multi-language then start at [[Help:Translate]].
|-
|[[File:de.gif]]
|Das FlightGear Wiki benötigt immer noch Hilfe bei der Übersetzung in verschiedene Sprachen. Wenn Du Interesse daran hast, das FlightGear Wiki Mehrsprachig zu machen, dann fang doch mit [[:de:Help:Übersetzen|Help:Übersetzen]] an.
|-
|[[File:nl.gif]]
|De FlightGear Wiki kan nog steed hulp gebruiken bij het vertalen van artikelen. Als je interesse hebt om de wiki meertalig te maken, raden we je aan om een kijkje te nemen bij [[:nl:Help:Vertalen|Help:Vertalen]].
|-
|[[File:es.gif]]
|La FlightGear wiki todavía necesita ayuda para traducirla a varios lenguajes. Si estás interesado en hacer la FlightGear wiki multilingüe, entonces comienza en [[:es:Help:Traducir|Help:Traducir]].
|}

{{Newsletter-article-start|Call for volunteers||And finally...}}
* The [[TerraGear]] maintainers are looking for volunteers to help with development on the next world scenery project. If you've ever wondered how a full 3D model of earth can be generated from raw data, now is your chance. See the plan at [[TerraGear roadmap]].

[[Category:FlightGear Newsletter|2014 06]]
[[Category:Changes after 3.00]]

Howto:Animate gear scissors

2014-06-29T08:59:46Z

TheTom: Tracking Animation

This [[:Category:Howto|HOWTO]] describes how to create an animation for landing gear scissors using an interpolation lookup table and no [[nasal]] code.

{{Note|For FlightGear 2.11+ the [[Tracking_animation|trackking animation]] provides a more accurate and easier way of animating gear scissor.}}

== Required tools ==
* A tool to measure distances in 3D models like [[AC3D]] or [[Blender]]. The images shown in this HOWTO uses AC3D but any other application should be fine.
* The standalone version of the nasal interpreter. Get it here: [http://www.plausible.org/nasal/ http://www.plausible.org/nasal/]
* A XML editor or a plain text editor. EDLIN should do but there are probably others...
* This little peace of nasal code. Copy and paste this code into a file called '''gearscissor.nas'''.
import("math");
var acos = func(x) { math.atan2(math.sqrt(math.abs(1-x*x)), x) }
var R2D = 180.0 / math.pi;

var scissor_dist = PUT SCISSOR_DIST HERE;
var scissor = PUT SCISSOR HERE;
var oleo = PUT OLEO HERE;

var theta0 = acos(scissor_dist/2/scissor) * R2D;
print( "<?xml version = '1.0' encoding = 'UTF-8' ?>\n" );
print( "<PropertyList>\n" );

for( var i = 0; i < 1.05; i += 0.05 ) {
print( "<entry>\n" );
var l = (1.0-i) * oleo/2;
l += (scissor_dist-oleo)/2;
print( "<ind>" ~ sprintf("%4.3f", i ) ~ "</ind>\n" );
print( "<dep>" ~ sprintf("%4.3f", acos( l / scissor ) * R2D - theta0 ) ~ "</dep>\n" );
print( "</entry>\n" );
}
print( "</PropertyList>\n" );

== Let's go ==
[[File:Howto- animate gear scissors scissor dist.jpg|thumb|250px|The scissor distance]]
First open the 3D model in AC3D and look for the gear to animate. The two scissor elements need to be named as individual objects. Let's call them '''A''' and '''B''' as an example. It is not within the scope of this document to describe how to create or name objects in the 3D model.
Our first step is to create the interpolation table to be included in the animation xml file.
Open your above created file gearscissor.nas in a text editor and look for the line
var scissor_dist = PUT SCISSOR_DIST HERE;
Measure the distance between the two vertices marking the two rotation axes of the two scissor elements. Check the image on the right, the two vertices are marked as green dots. Replace the text PUT SCISSOR_DIST HERE with this value.

[[File:Howto- animate gear scissors scissor.jpg|thumb|250px|The scissor length]]
Next, measure the distance between the two rotation axes of one scissor arm. Check the image on the right as a visual reference. Put the value into the line
var scissor = PUT SCISSOR HERE
and replace the text PUT SCISSOR HERE with this value.

[[File:Howto- animate gear scissors oleo.jpg|thumb|250px|The oleo strut]]
Finally you need the length of the oleo strut, the maximum compression length of the oleo strut. Measure the distance like in the examle image and place the value into the line
var oleo = PUT OLEO HERE;
Replace PUT OLEO HERE with the value.

Save the file, and run the file through the nasal interpreter by calling
nasal gearscissor.nas

This should produce a lot of output. This is the interpolation table that checks the compression of the gear strut and derives the angular deflection of the scissor arm. It should look like this:
<?xml version = '1.0' encoding = 'UTF-8' ?>
<PropertyList>
<entry>
<ind>0.000</ind>
<dep>-0.074</dep>
</entry>
<entry>
<ind>0.050</ind>
<dep>3.816</dep>
</entry>
<entry>
<ind>0.100</ind>
<dep>7.345</dep>
...
</PropertyList>
Your numbers will look different but the structure should be the same. Save this output into a file named '''GearScissorInterpolation.xml''' and save this file in the same folder where your 3D model lives.
Note: in a console environment, you can usually save a program's output by forwarding it to a file using the > operator:

./nasal gearscissor.nas > GearScissorInterpolation.xml

== The animation XML ==
Before you continue, locate the rotation points of the two scissor arms where they are connected to the main strut. These are the vertices that were marked to measure the scissor distance.
Open the XML file that contains the animations for you model and add the following lines within the <PropertyList></PropertyList> elements:
<animation>
<type>rotate</type>
<object-name>A</object-name>
<property>gear/gear[1]/compression-norm</property>
<axis>
<x>-1</x>
</axis>
<center>
<x-m>YOUR X LOCATION OF THE ROTATION POINT HERE</x-m>
<y-m>YOUR Y LOCATION OF THE ROTATION POINT HERE</y-m>
<z-m>YOUR Z LOCATION OF THE ROTATION POINT HERE</z-m>
</center>
<interpolation include="GearScissorInterpolation.xml"/>
</animation>
Fill in your values for x-m, y-m and z-m for the location of the rotation vertices. Add another section for the second scissor arm, replace the object-name with '''B''' and set the axis to +1 instead of -1.
If you see the scissors move in the opposite direction, exchange the sign in the axis definition.

== Examples ==
Check out the [[Hamburger Flugzeugbau HFB 320 Hansa Jet|HansaJet]] and the [[Piper PA34-200T Seneca II|Seneca II]]. Both [[aircraft]] use the above technique for the animation.

[[Category:Howto|Animate gear scissors]]
[[Category:Modeling|Animate gear scissors]]

Canvas event handling

2014-06-28T10:45:40Z

TheTom:

[[Category:Canvas]]
{{Template:Canvas Navigation}}

'''Note: This feature is only available in FlightGear versions >= 2.11 !'''

The Canvas event handling system closely follows the W3C [http://www.w3.org/TR/DOM-Level-3-Events/ DOM Event Model]. If you have already used events in JavaScript and HTML most concepts of the Canvas event system should be already familiar to you. The most notable difference is the missing capture phase, but it is usually not used anyhow.

Listeners - simple Nasal functions - can be attached to every element inside the Canvas and the Canvas itself. Once a certain action - like moving the mouse or pressing a button - occurs the associated listeners are called. We can use this for example to detect whether the mouse has moved over an element or if a certain element has been clicked.

= Listen for events =

To receive events callback function can be added to elements on a Canvas as well as to the Canvas itself:

<syntaxhighlight lang="nasal">
canvas.addEventListener("<type>", <func>);
canvas_element.addEventListener("<type>", <func>);
</syntaxhighlight>

For each placement of a Canvas handling events can be enabled or disabled. A Canvas placed in a PUI (old GUI) widget or as standalone GUI window receives events by default, whereas Canvases placed onto the aircraft model or in the scenery do not receive any events by default.

{{Note|The old [[Howto:Adding_a_canvas_to_a_GUI_dialog|PUI/XML GUI]] does not trigger any mouseover/hover events. Mouse clicks/wheel/drag are working as expected. For all other placements like on standalone Canvas windows and [[Howto:Add_a_2D_canvas_instrument_to_your_aircraft|3D models]] there is no such limitation.}}

For standalone GUI windows setting '''capture-events''' to ''0'' or ''1'' enables or disables handling of events respectively. For a Canvas placed onto a 3d model, setting ''capture-events'' inside the placement can be used to activate event handling:

<syntaxhighlight lang="nasal">
var dlg = canvas.Window.new([152,74]);

# Disable event handling for this window. Events will pass through
# and can reach any window or also object covered by the window.
dlg.setBool("capture-events", 0);

# Place the canvas onto the PFD and enable receiving events
my_canvas.addPlacement({"node": "PFD-Screen", "capture-events": 1});
</syntaxhighlight>

= Event flow =

Events always are targeted at a specific element inside the Canvas. Before any event handler is called the propagation path for the event is determined. It consists of the event target itself and all its ancestor elements (Groups) up to and including the Canvas. Afterwards - during the ''Target Phase'' - all listeners registered on the event target are called. Finally - during the ''Bubbling Phase'' - the event bubbles up the tree, following the propagation path determined in the first step, and all listeners attached to the according elements are called.

[[File:Canvas Eventflow.png|thumb|540px|center|Event flow of Canvas Events similar to W3C DOM Event flow <ref name="dom-event-flow">DOM Level 3 event flow. http://www.w3.org/TR/DOM-Level-3-Events/#event-flow</ref>.]]

= Event classes =

<syntaxhighlight lang="nasal">
var Event = {
# Name of event type [read-only]
type: <typename>,

# Target element [read-only]
target: <target-element>,

# Element the currently called listener is attached to [read-only]
currentTarget: <target-element>,

# Stop further propagation of event (stop
# bubbling up to its parents)
stopPropagation: func()
};

var MouseEvent = {
parents: [Event],

# Position in screen coordinates [read-only]
screenX: <screen-x>,
screenY: <screen-y>,

# Position in window/canvas coordinates [read-only]
clientX: <client-x>,
clientY: <client-y>,

# Position in local/element coordinates [read-only]
localX: <local-x>,
localY: <local-y>,

# Distance to position of previous event [read-only]
deltaX: <delta-x>,
deltaY: <delta-y>,

# Current click count (number of clicks within a certain
# time limit. max. 3) [read-only]
click_count: <click-count>,

# Buttons/modifiers require FlightGear >= 3.1.0

# Button which triggered this event [read-only]
#
# 0: primary button (usually the left button)
# 1: auxiliary button (usually the middle button/mouse wheel)
# 2: secondary button (usually the right button)
button: <button>,

# State of all mouse buttons at the time the event has been
# triggered [read-only]
buttons: <active-button-mask>,

# State of all keyboard modifiers at the time the event has
# been triggered [read-only]
modifiers: <modifier-mask>,

# [read-only]
ctrlKey: <was-ctrl-down>,

# [read-only]
shiftKey: <was-shift-down>,

# [read-only]
altKey: <was-alt-down>,

# [read-only]
metaKey: <was-meta-down>
};
</syntaxhighlight>

== Middle-mouse button emulation ==

2-button mice can be setup to emulate a middle-mouse button click by pressing the left and right button simultaneously. On Ubuntu you can use [https://apps.ubuntu.com/cat/applications/gpointing-device-settings gpointing-device-settings] to enable "middle button emulation"
<ref>https://wiki.ubuntu.com/X/Quirks#A2-button_Mice</ref>
<ref>http://askubuntu.com/questions/140828/how-can-i-paste-text-by-pressing-the-left-and-right-mouse-buttons-at-the-same-ti</ref>.

= Event types =
{| class="wikitable"
|-
! Type !! Description !! DOM equivalent event !! Bubbles <ref name="dom-event-flow"/>
|-
| ''mousedown'' || Mouse button pressed || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mousedown mousedown] || {{tick}}
|-
| ''mouseup'' || Mouse button released || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseup mouseup] || {{tick}}
|-
| ''click'' || ''mousedown'' + ''mouseup'' have been triggered for this element without moving more than a certain maximum distance || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-click click] || {{tick}}
|-
| ''dblclick'' || Two ''click'' events have been triggered for this element without moving more than a certain maximum distance and time limit || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-dblclick dblclick] || {{tick}}
|-
| ''drag'' || The mouse has been moved with a button down. After dragging has started above an element, all consecutive ''drag'' events are sent to this element even if the mouse leaves its area || || {{tick}}
|-
| ''wheel'' || Mouse wheel rotated (see deltaY for direction) || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-wheel wheel] || {{tick}}
|-
| ''mousemove'' || Mouse has moved while beeing inside the area of the target element. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mousemove mousemove] || {{tick}}
|-
| ''mouseover'' || Mouse has entered a child or the element itself. ''mouseover'' is also triggered if the mouse moves from one child element to another. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseover mouseover] || {{tick}}
|-
| ''mouseout'' || Mouse has left a child or the element itself. ''mouseout'' is also triggered if the mouse moves from one child element to another. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseout mouseout] || {{tick}}
|-
| ''mouseenter'' || Mouse has entered a child or the element itself. In contrary to ''mouseover'', ''mouseenter'' is not triggered if the mouse moves from one child element to another, but only the first time the element or one of its children is entered. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseenter mouseenter] || {{cross}}
|-
| ''mouseleave'' || Mouse has left the element and all of its children. In contrary to ''mouseout'', ''mouseleave'' is not triggered if the mouse moves from one child element to another, but only if the mouse moves outside the element and all its children. || [http://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseleave mouseleave] || {{cross}}
|}

= Example Code =
For the latest examples, please refer to [https://gitorious.org/~tomprogs/fg/toms-fgdata/commits/canvas-gui-demo Tom's canvas-gui-demo branch on gitorious]. This is also where you can find the following code in $FG_ROOT/Nasal/canvas/gui.nas (note that this example makes use of advanced Nasal concepts, such as anonymous functions, method chaining and lots of embedded/inline code):
<syntaxhighlight lang="nasal">
# Canvas GUI demo
#
# Shows an icon in the top-right corner which upon click opens a simple window
#
(func {
var init_gui = setlistener("/nasal/std/loaded", func() {
removelistener(init_gui);
var dlg = canvas.Window.new([32,32]);
dlg.setInt("tf/t[1]", 4)
.setInt("right", 4);
var my_canvas = dlg.createCanvas()
.setColorBackground(0,0,0,0);
var root = my_canvas.createGroup();
canvas.parsesvg(root, "gui/dialogs/images/icon-aircraft.svg");

my_canvas.addEventListener("click", func
{
var dlg = canvas.Window.new([400,300], "dialog");
var my_canvas = dlg.createCanvas()
.set("background", "#f2f1f0");
var root = my_canvas.createGroup();
root.addEventListener("click", func(e) { printf("click: screen(%.1f|%.1f) client(%.1f|%.1f) click count = %d", e.screenX, e.screenY, e.clientX, e.clientY, e.click_count); });
root.addEventListener("dblclick", func(e) { printf("dblclick: screen(%.1f|%.1f) client(%.1f|%.1f)", e.screenX, e.screenY, e.clientX, e.clientY); });
root.addEventListener("wheel", func(e) { printf("wheel: screen(%.1f|%.1f) client(%.1f|%.1f) %.1f", e.screenX, e.screenY, e.clientX, e.clientY, e.deltaY); });
var text =
root.createChild("text")
.setText("This could be used for building an 'Aircraft Help' dialog.\nYou can also #use it to play around with the new Canvas system :). β")
.setTranslation(10, 30)
.setAlignment("left-top")
.setFontSize(14)
.setFont("LiberationFonts/LiberationSans-Regular.ttf")
.set("max-width", 380)
.setColor(0,0,0);
var text_move =
root.createChild("text")
.setText("Mouse moved over text...")
.set("character-size", 15)
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")
.set("alignment", "left-center")
.setTranslation(20, 200)
.set("fill", "#ff0000")
.hide();
var visible_count = 0;
text.addEventListener("mouseover", func text_move.show());
text.addEventListener("mouseout", func text_move.hide());
});
});
})();
</syntaxhighlight>

<references/>

Canvas widgets

2014-06-24T10:15:56Z

TheTom:

{{Template:Canvas Navigation}}

As of 07/2012, there's a general consensus to replace the current FlightGear GUI (based on PLIB/PUI) by using the new Canvas system.

However, before we can work on adding new widgets to FlightGear, we need to provide wrappers for the existing hardcoded PUI widgets, see [[Canvas GUI]].

Canvas widgets are dynamically created GUI widgets that use the [[Canvas]] subsystem to create custom, owner-drawn, GUI widgets in a scripted fashion using [[Nasal]]. The textures are conventional canvas textures, however they are rendered by the GUI system, so that scripted event handlers can be implemented which respond to GUI events, such as keyboard/mouse input or other events (resize, update, redraw etc).

Using canvas widgets, it will be possible to create your own GUI styles and even completely new, fully interactive, GUI controls (buttons, text boxes, list views, tree views etc) just by using Nasal, without touching any C++ code and without rebuilding FlightGear. The Canvas system supports loading SVG files and raster images, so that canvas elements and GUI widgets can be assembled from SVG elements, meaning that you'll be able to use a conventional SVG editor like Inkscape to create/edit FlightGear GUI widgets.

== The Idea ==
This section lists a bunch of ideas related to supporting Canvas textures for GUI drawing needs, i.e. to render Canvases as textures, but also to increasingly implement parts of the GUI (such as custom widgets) using interactive Canvases with scripted callbacks, the idea is to work around existing GUI/PUI shortcomings by using Canvases to implement custom styles and widgets.

{{cquote|<nowiki>We
could could allow aircraft dialogs to include custom widgets, although that
might be unwise for other reasons</nowiki><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg37868.html|title=<nowiki>Re: [Flightgear-devel] Switching from PUI to osgWidget</nowiki>|author=<nowiki>James Turner</nowiki>|date=<nowiki>Tue, 24 Jul 2012 10:36:26 -0700</nowiki>}}</ref>|<nowiki>James Turner</nowiki>}}

<references/>

== The Plan ==
In contrast to using some hardcoded GUI system (PUI, osgWidget, etc.) this approach would give much more flexibility and also the means of modifying and creating new widgets without the need to touch any core code.

With the Canvas system every type of widget would be possible, so that also things like submenus can be realized.

Another advantage of the Canvas approach is that it is heavily using the property tree and therefore is already fully accessible from Nasal code and also configurable with the existing xml formats. [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg37861.html]

The point of the canvas widget demo is to demonstrate how powerful and flexible the new canvas system really is, i.e. it cannot just be used for aircraft scripting (instruments, MFDs), but also for GUI scripting - which means that using the canvas system would unify the 2D rendering backend (all 2D rendering can be handled via canvas), while reducing the amount of C++ code we have doing these things, which would mean that the GUI system could be entirely maintained in scripting space, i.e. as part of the base package, by people who don't need to know C++ - some basic Nasal knowledge will do.

Basically, adopting the new canvas system for such and similar purposes, will mean that tons of old/oudated C++ code can be phased out and replaced by a single consistent implementation in C++, that is using modern C++/OSG code - which ultimately also means that OSG itself can make more assumptions about what's being rendered, so that more optimizations (= better frame rates) can be more easily accomplished by using OSG coding patterns and protocols in a single place, instead of outdated/custom/3rd party libraries which would need to be manually baked into the existing FG/SG/OSG eco system.

Currently, the canvas system is integrated in such a fashion that it will keep working with the old GUI code still in place.In addition, all of the exsting GUI features (layouting, XML processing) are implicitly supported due to the way the canvas system is implemented at the moment. These are real roadblocks when implementing a new GUI library next to PUI, because all of the existing stuff would need to be explicitly ported (either in C++ space or by converting tons of XML files).

Overall, the canvas system will give us all of this "for free", and it will mean less C++ code in the source tree, too - i.e. better maintainability.

Also, once the standalone "FGCanvas" is available, it would also be possible to run the GUI in multiple windows or even in separate processes.

In addition, by using the canvas system for GUI widgets, it would also be possible to render aircraft instruments, MFDs, HUDs etc WITHIN GUI dialogs, too.

== Status (06/2014) ==
{{warning|The canvas gui always handles events first and only if no window was hit forwards events to scenery picks and PUI dialogs. Which means that PUI (old) dialogs rendered on top of new canvas windows, will not receive their GUI events currently. With FlightGear 3.1+ this is no problem anymore, as Canvas windows are drawn on top of PUI dialogs to match the rendering order and the event handling order.}}

* '''TheTom''' (05/2013): "I'm still not completely sure how to implement the GUI, but currently I'm thinking of something similar to most available UI toolkits with mainly using images together with 9-scale/slicing. Theming would be possible by simply exchanging the images and/or modulate them with a color. For some icons/elements also SVG could be used, and maybe I'll implement the possibility to cache rendered images of SVG elements for faster rendering of them." [http://forum.flightgear.org/viewtopic.php?f=71&t=19850#p182509]
* '''TheTom''': (30/07/2012) I have now pushed some updates to my branch. It is now possible to create windows (texture rectangles) with just using the property tree and place a canvas texture onto it. Mouse events are passed to the active window (=the window the cursor is hovering over, or for dragging the window where the drag gesture started) and can be handled from Nasal or anything else that has access to the property tree.

{{#ev:youtube|1a6wtPVPWc4}}
{{#ev:youtube|CIS8UyuJLgM}}
{{#ev:youtube|Qv-uEX42QZY}}
{{#ev:youtube|llVaasTEf44}}

=== Missing / Todo ===
Last updated: 08/2012

List of missing things (if you'd like to get involved to help with any of these, please get in touch via the [http://forum.flightgear.org/viewforum.php?f=71 canvas forum]):
==== Misc ====
* '''Documentation''': Read, ask questions, extend. I haven't done too much documentation (apart from inline documentation) just due to the reason that the API is not completely stable yet. You could also try different use-cases and maybe find some examples where the API lacks some features.{{Not done}}
* '''Own ideas''': Come up with a new idea or something that I have already mentioned somewhere else {{Feedback}}
* Find more work I've currently forgotten about :) {{Feedback}}

==== C++ ====
* '''[[#Keyboard Handling|Keyboard input]]''': I haven't thought too much about it and also haven't done anything, but we will definitely need access to keyboard events {{Not done}}
* '''Clipping''': For different reasons we will need to be able to clip some elements to certain regions. It should work with specifying either a clipping rectangle or by using a path. OpenVG seems to have support for it, although I haven't looked into it too deep. We also need to ensure that it also works with text. At least rectangular regions are needed.(eg. group/clip-min[0..1], group/clip-max[0..1]) {{Not done}}
* '''Animations''': I don't know if we should do animations just by using interpolator and settimer from Nasal or if we should implement some time-based animations directly in C++. At least we need some helper functions (eg. for blinking elements -> cursor, fading, ...) It would also be possible to implement animations purely in Nasal space, e.g. by supporting a subset of SMIL for SVG, so that existing tools could be used to created animated vector images that are converted to canvas properties by the Nasal parser.
* Check what is missing to implement the different hardcoded instruments.{{Not done}}
* provide Nasal hooks to access: taxiways, <del><parking positions</del> etc
* Maybe support displaying shapefiles.{{Not done}}
* '''Unify the canvas creation a bit''': such that canvases can be moved seamlessly between the different placements (gui, model,hud, etc.). The normal model placement is great but the gui widget placement needs to be able to also use an already existing canvas.{{Not done}}
* '''Support multiple views/windows''': Currently the GUI can only be placed inside one view/window (see Docs/README.multiscreen) but it would be nice to be able to move windows between views.{{Not done}}

==== Nasal ====

* '''[[Canvas_Widgets#Widget_Declaration_via_SVG|Extend gui.nas to support loading widgets from SVG files]]''': We want to be able to load widgets from SVG files and link them to Nasal code in [[$FG_ROOT]]/Nasal/widgets - for example: [[$FG_ROOT]]/Nasal/widgets/button.nas {{Not done}}
* '''[[Canvas_Widgets#Nasal_requirements|Implement Widgets]]''': {{Not done}}
* '''[http://wiki.flightgear.org/Canvas_Widgets#Layout_Management_.28_.28Not_done.29.29 Layout Handling]''': {{Not done}}
* '''[[Canvas_Widgets#Dialog_Parser|Implement the dialog/xml parser]]''': {{Not done}}
* '''[http://wiki.flightgear.org/Canvas_Widgets#Styling.2C_Theming_and_Skinning_.28XSL.2FCSS_via_SVG.29 Implement a generic CSS/XSL-based styling class]''': (Could also be used to implement styling support of the current GUI) {{Not done}}
* '''[[Canvas Maps|Geographic Mapping]]''': It's very experimental, missing different projection modes (eg. vertical projection) and especially the Nasal API feels very hackish. {{Progressbar|50}}
* '''Improve the Nasal API''': Add some helper functions for animating different glass cockpit displays (I have already some basic code, but it needs some generalization).

== Fully Canvas based implementation (in progress as of 08/2012) ==
This section describes a possible way of completely getting rid of PUI and providing a GUI system by only using the Canvas system.

=== C++ core requirements {{Pending}} ===
{{Progressbar|40}}

Certain properties can be set to affect the appearance and behavior of the dialog:

* Initial position
* Dragable
* Resizeable
** If true, min/max/initial size
** If false, size
* Modal
* Texture coordinates (allow using just part of the canvas, eg. to have enough space for larger window after resize)
* ...

* The Canvas manager needs to be extended to support using such a window as target for a placeable definition. If a window is resizeable the size property nodes will be updated to allow the canvas and/or its viewport being resized. {{Done}}
* It would be also be good to allow the canvas textures to be resized at runtime, so that we don't have to reserve to large canvases just because the dialogs could be resized. {{Pending}}
* The GUI system should take care of handling and forwarding mouse and keyboard events to the property tree as needed (Some parts of the existing code could probably be reused). Eg. if a canvas is assigned picking should occur on mouse clicks and forwarded to the property tree. {{Pending}}
* The existing dialog-show command needs to be modified to call the according function in Nasal space which will handle the whole creation and updating of the GUI. {{Pending}} (can be done by using the new removecommand/addcommand APIs meanwhile)

=== Keyboard Handling ===
{{Feedback}}

Looking at the mouse handling code, the same technique we use for mouse handling could obviously also be used for keyboard handling:
* http://www.openscenegraph.org/documentation/NPSTutorials/osgKeyboardInput.htm
* http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/BasicKeyboardInput

So it just involves checking for osgGA::GUIEventAdapter::KEYDOWN and propagating the events to a handful of child properties for each canvas element that subscribed to keyboard events.

It'd make sense to also use a boolean property to enable/disable reception of keyboard events, that will allow us to set the "focus" of windows and widgets. And then we only need to expose some keyboard-specific events like key-up, key-down, key-value etc at the C++ level, which all boils down to just calling fgSet*Value().

The rest will be handled at the Nasal level, so that users can register their own listeners.

The nice thing is that once this is properly implemented, we'll already have a unified I/O handling system for GUIs, instruments, HUDs etc. and it moves all the implementation details to the base package again.

BTW: There is already a property to toggle the mouse cursor via setprop, so this could also be wrapped in gui.nas, obviously being able to use a canvas texture as the cursor would prove the point that "everything is a canvas" in the design.

I was looking through our earlier discussions, and how osgGA can be used for keyboard support.
And like I mentioned, I think it would make sense to adopt the same approach that you used for mouse support here.

Overall, I feel it would make sense to closely model this after the way this is handled in Java, i.e. using the same "property events" that are supported in Java for mouse/keyboad and "windows" - just specific to canvas textures, instead of just "windows".

So instead of "window" events, we'd have "texture" events, so that these can also be used for non-GUI purposes, such as instruments

Looking at our last discussion on forwarding mouse events to nested canvases, it would then really make sense to also have "window/texture" events (create, update, redraw, resize, move etc). So that we don't need to add any C++ code for such things.

And by having "high level" events such as "mouse-enter", "mouse-leave" or "texture-resize", "texture-moved", "has-focus","lost-focus" etc, it would be very simple to implement MFDs and GUI widgets in Nasal without requiring C++ workarounds.

So it's really just about supporting 10-15 event types in the C++ code which set some properties, so that the rest can be implemented in Nasal.

Obviously, some events would be texture specific, while others would be specific to groups or elements and should probably be forwarded, like you suggested earlier.

And then it'd be very close to how this is handled in Java, because we could use conventional Nasal listener callbacks to model the details in scripting space.

Specialized widgets could then use these events to implement widget-specific events, i.e. for list view, tree views or other complex widgets - but these could then be implemented in Nasal.

We probably want to support Java-style Key listeners and Key bindings, so that widget-behavior can be easily implemented in Nasal space

=== Nasal requirements ===
{{Feedback}}

* <del>The API needs to be extended to allow the creation of windows and placing canvases onto them.</del> {{Done}}
* We also need a function which parses existing dialog xml files (reimplementing http://gitorious.org/fg/flightgear/blobs/next/src/GUI/FGPUIDialog.cxx#line708 FGPUIDialog.cxx/FGPUIDialog::makeObject]) and maps them to the new canvas widgets. Each widgets sits in is own Nasal file (eg. inside $FG_DATA/gui/widgets) and has to be implemented using a hash with several required functions, implementing the abstract interface of a widget:

<syntaxhighlight lang="nasal">
var SampleWidget = {
# Add the widget to the parent
#
# @param config A hash containing all parameters for this widget.
new: func(parent, config),
# Get the minimal required size. Used for positioning following elements
# if no absolute coordinates are given and to calculated available space
# for widgets with vertical or horizontal stretch enabled.
getMinSize: func(),
};
</syntaxhighlight>

In addition, the interface should probably contain methods to:

* show/hide widget
* destroy widget
* enable/disable propagation of events (mouse/keyboard)

Also, we are currently able to reload the GUI in FlightGear, we will want to retain this feature. But once we start implementing widgets in Nasal, we won't just want to reload the GUI XML files, but also the widget modules from [[$FG_ROOT]]/Nasal/widgets, so that widgets can be easily developed and tested, without having to restart FG.

This can be implemented in Nasal space, there's no need to modify the Nasal sub modules code for this - however, we also need to ensure that there's a sane way to terminate all active widgets, i.e. by stopping all running instances. This will also be important to handle simulator reinit/reset.

Thus, during instantiation, all widgets would need to register a listener, so that they can be terminated properly using a signal property.

=== Dialog Parser ===
{{Feedback}}

* [https://gitorious.org/fg/fgdata/blobs/master/Docs/README.gui [[$FG_ROOT]]/Docs/README.gui]
* [http://gitorious.org/fg/flightgear/blobs/next/src/GUI/FGPUIDialog.cxx#line710 Supported Widget Types]

The '''parsegui''' function parses a dialog xml file and calls the constructor of the corresponding widget.
'''The GUI parser should handle XML versioning, so that future updates to the underlying XML format can be easily supported, without tons of custom code. It might make sense to provide a base class, so that future parsers can be easily implemented next to the existing code, so that new parsers don't need to touch any of the old code!'''

We need to keep the existing way of specifying GUI files via XML - it's a nice, declarative way of building the dialogs. Switching to an imperative system would be a step backwards. I do like the idea of a gui/widget/widgetname.nas structure so we can easily create a factory function and hack / add widgets.

It is important to keep in mind that the Canvas system will have at least 3 related uses:
* HUDs {{Pending}}
* GUIs {{Pending}}
* 2D panels {{Pending}}

All of these will require an XML parser that turns the existing structure into canvas nodes. The existing SVG parser is purely implemented in scripting space (see svg.nas) using the XML parser in [[$FG_ROOT]]/Nasal/io.nas

Given that all three file formats are PropertyList-encoded XML files, it should be possible to come up with a "Xml2Canvas" interface class which implements the XML parser and the Canvas interfaces. That will ensure a maximum degree of code reuse.

Afterwards the getMinSize method is used to calculated the available space and stretch widgets if required.

To ensure that the core widgets in [[$FG_ROOT]]/Nasal/widgets cannot be accidently invalidated by users, the widget namespace/hash will be made immutable using globals.nas magic.

=== Building Widgets at the C++ Level ===

We can always create widgets from C++ by adding canvas elements directly through the property tree, but I think a fully scripted GUI is the most flexible and powerful approach. Let's keep in mind that all the original hard coded PUI dialogs were increasingly replaced with XML dialogs in FlightGear, which was important and a lot of work.

One of the most important goals of the canvas system is to make 2D drawing accessible to end users, without having to know C++ and without having to rebuild FlightGear. This automatically means that large parts of FlightGear will become more maintainable, because they can be moved over to the base package. Starting to implement GUI widgets at the C++ level would defeat the purpose.

While it would definitely be possible to implement widgets by directly creating a canvas via the property tree, that would probably be counter-productive, because we clearly don't want any hard coded C++ special cases.

Now, if someone really wants to implement some custom canvas widget that cannot/shouldn't be modeled in scripting space, then the canvas infrastructure can be extended.

Just take a look at how the existing [[Canvas Maps]] are implemented currently. The same approach could be used to provide support for new/more specific drawing modes, such as:

* aircraft/3D model previews
* scenery cameras
* or moving map layers
* shapefiles

The canvas isn't really about end user features, it's a provider of an infrastructure, so that end user features can be more easily expressed and modeled in scripting space, using Nasal. That's why all end user features should be expressible in scripting space, and only the core infrastructure should need C++ extensions to make this easier. The end user APIs will be mostly designed in scripting space.

== Related ==
* http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg37854.html

== Related Discussions ==
* [http://sourceforge.net/tracker/index.php?func=detail&aid=1495800&group_id=583&atid=350583 05/2006: PUI shortcomings]
* [http://sourceforge.net/mailarchive/forum.php?thread_name=01C87FCC.5E28B080.johnffay%40cybertron.com&forum_name=plib-devel 03/2008:plib devel discussion on possibly depreciating pui]
* [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18501.html 10/2008:OSGWidget]
* [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg20793.html 01/2009:PUI vs. OSGWidget]
* [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg22427.html 06/2009:PLIB/PUI restrictions]
* [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg22510.html 06/2009:OSGWidget related]
* [http://sourceforge.net/mailarchive/message.php?msg_name=m1ab0ew87h.fsf%40usa.net 09/2009:Atlas migrating from PUI to FLTK]
* [http://sourceforge.net/mailarchive/forum.php?thread_name=m18wbx49pu.fsf%40usa.net&forum_name=atlas-devel 01/2010: Migrating Atlas to FLTK (limitations)]
* [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg25976.html 01/2010:GUI dialogs suck]
* [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg25991.html 01/2010:GUI dialogs suck]

Canvas MessageBox

2014-06-23T15:56:03Z

TheTom: Missing Navigation...

{{Template:Non-stable|version=3.2|progress=100}}
{{Template:Canvas Navigation}}

Message boxes provide a simple way to report information and warnings or ask questions. In FlightGear 3.1+ using <code>canvas.MessageBox</code> with the Nasal scripting language, allows showing standard message boxes to the user.

== Predefined Severity Levels/Icons ==
{| class="wikitable"
|-
! Icon !! Icon Name !! Standard MessageBox !! Description
|-
| style="text-align:center;" | [[File:Dialog-question.png|link=]] || <code>"dialog-question"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.question(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Yes
| canvas.MessageBox.No
);</syntaxhighlight> || Ask the user a (yes/no) question.
|-
| style="text-align:center;" | [[File:Dialog-info.png|link=]] || <code>"dialog-info"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.information(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Ok
);</syntaxhighlight> || Show the user some information, with only the possiblity to close the dialog.
|-
| style="text-align:center;" | [[File:Dialog-warning.png|link=]] || <code>"dialog-warning"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.warning(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Ok
);</syntaxhighlight> || Show the user a non critical warning, with only the possiblity to close the dialog.
|-
| style="text-align:center;" | [[File:Dialog-error.png|link=]] || <code>"dialog-error"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.critical(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Ok
);</syntaxhighlight> || Notify the user of a critical error or failure, with only the possiblity to close the dialog.
|}

== Examples ==

{|
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo information.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.info("Success", "The operation has successfully completed.");
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo question.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.question(
"Do you want it?",
"The question is: Do you want to get a real question?.",
func(sel)
{
if( sel == canvas.MessageBox.Yes )
print("I only know that the answer is 42.");
else
print("Ok, I will not give you a real question.");
}
);
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo warning dont-show-again.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.warning(
"Warning...",
"Have you read this warning? If you want it will not be shown again.",
func(sel)
{
if( sel != canvas.MessageBox.Ok )
return;

print("You have been warned. Let the games begin...");
},
canvas.MessageBox.Ok
| canvas.MessageBox.Cancel
| canvas.MessageBox.DontShowAgain
);
</syntaxhighlight>
|}

Canvas MessageBox

2014-06-23T15:51:27Z

TheTom: First proper version. Examples, Severity levels...

Message boxes provide a simple way to report information and warnings or ask questions. In FlightGear 3.1+ using <code>canvas.MessageBox</code> with the Nasal scripting language, allows showing standard message boxes to the user.

== Predefined Severity Levels/Icons ==
{| class="wikitable" style="width:100%"
|-
! Icon !! Icon Name !! Standard MessageBox !! Description
|-
| style="text-align:center;" | [[File:Dialog-question.png|link=]] || <code>"dialog-question"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.question(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Yes
| canvas.MessageBox.No
);</syntaxhighlight> || Ask the user a (yes/no) question.
|-
| style="text-align:center;" | [[File:Dialog-info.png|link=]] || <code>"dialog-info"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.information(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Ok
);</syntaxhighlight> || Show the user some information, with only the possiblity to close the dialog.
|-
| style="text-align:center;" | [[File:Dialog-warning.png|link=]] || <code>"dialog-warning"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.warning(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Ok
);</syntaxhighlight> || Show the user a non critical warning, with only the possiblity to close the dialog.
|-
| style="text-align:center;" | [[File:Dialog-error.png|link=]] || <code>"dialog-error"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.critical(
<title>,
<text>,
cb = nil,
buttons = canvas.MessageBox.Ok
);</syntaxhighlight> || Notify the user of a critical error or failure, with only the possiblity to close the dialog.
|}

== Examples ==

{| style="width:100%"
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo information.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.info("Success", "The operation has successfully completed.");
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo question.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.question(
"Do you want it?",
"The question is: Do you want to get a real question?.",
func(sel)
{
if( sel == canvas.MessageBox.Yes )
print("I only know that the answer is 42.");
else
print("Ok, I will not give you a real question.");
}
);
</syntaxhighlight>
|- style="vertical-align:top;"
| [[File:Canvas-MessageBox-demo warning dont-show-again.png|link=]] ||
<syntaxhighlight lang="nasal">
canvas.MessageBox.warning(
"Warning...",
"Have you read this warning? If you want it will not be shown again.",
func(sel)
{
if( sel != canvas.MessageBox.Ok )
return;

print("You have been warned. Let the games begin...");
},
canvas.MessageBox.Ok
| canvas.MessageBox.Cancel
| canvas.MessageBox.DontShowAgain
);
</syntaxhighlight>
|}

File:Canvas-MessageBox-demo warning dont-show-again.png

2014-06-23T15:42:50Z

TheTom: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=Canvas MessageBox showing a warning. The answer is saved if the user selects Don't show again.}}
|date=2014-06-23 17:42:11
|source={{own}}
|author=[[User:TheTom|TheTom]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Canvas]]

File:Canvas-MessageBox-demo question.png

2014-06-23T15:22:55Z

TheTom: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=Canvas question MessageBox.}}
|date=2014-06-23 17:21:11
|source={{own}}
|author=[[User:TheTom|TheTom]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Canvas]]

File:Canvas-MessageBox-demo information.png

2014-06-23T15:22:44Z

TheTom: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=Canvas information MessageBox.}}
|date=2014-06-23 17:21:05
|source={{own}}
|author=[[User:TheTom|TheTom]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Canvas]]

Canvas MessageBox

2014-06-23T14:49:41Z

TheTom: Created page with "{| class="wikitable" |- ! Icon !! Icon Name !! Standard MessageBox !! Description |- | link= || <code>"dialog-question"</code> || <syntaxhighlight..."

{| class="wikitable"
|-
! Icon !! Icon Name !! Standard MessageBox !! Description
|-
| [[File:Dialog-question.png|link=]] || <code>"dialog-question"</code> || <syntaxhighlight lang="nasal">canvas.MessageBox.question(title, text, cb = nil, buttons = asd aasd asdasdas asda sdsa dsad sads adsad sasda dasd asd)</syntaxhighlight> ||
|-
| [[File:Dialog-info.png|link=]] || "dialog-info" || '''canvas.MessageBox.question''' ||
|-
| [[File:Dialog-warning.png|link=]] || "dialog-warning" || '''canvas.MessageBox.question''' ||
|-
| [[File:Dialog-error.png|link=]] || "dialog-error" || '''canvas.MessageBox.question''' ||
|}

Template:Canvas Navigation

2014-06-23T14:36:59Z

TheTom: Add MessageBox. Remove outdated Readme.

{{forum|71|Canvas}}
{{sidebar
| name = Canvas Navigation
| title = Canvas - the FlightGear 2D drawing API
| contentstyle= text-align: left;

| content1 =
* [[Canvas]] - Main Page
* [[Canvas Development]]
* [[Canvas GUI]]
* [[Canvas Widgets]]
* [[Canvas Maps]]

| heading2 = Frameworks
| content2 =
{{Canvas Frameworks|mode=navbar}}
* [[Canvas Glass Cockpit Efforts]]

| heading3 = Tutorials
| content3 =
* [[Howto:Getting started with Canvas]]
* [[Howto:Adding a canvas to a GUI dialog]]
* [[Howto:Add a 2D canvas instrument to your aircraft]]
* [[Howto:Parsing 2D Instruments using the Canvas]]
* [[Howto:Creating fullscreen Canvas applications]]
* [[Howto:Use SVG inside a Canvas]]
* [[Howto:Canvas applications as Nasal submodules]]
* [[Howto:Using raster images and nested canvases]]

* [[Howto:Creating a Canvas graph widget]]
* [[Canvas HUD]]
| heading4 = Reference
| content4 =
* [[Canvas Element]]
** [[Canvas Group|Group]]
** [[Canvas Image|Image]]
** [[Canvas Map|Map]]
** [[Canvas Path|Path]]
** [[Canvas Text|Text]]
* [[Canvas Nasal API]]
** [[Canvas MessageBox|MessageBox]]
* [[Canvas - Event_Handling|Event Handling]]
| heading5 = Related
| content5 =
* [[Canvas Properties]]
* [[Unifying the 2D rendering backend via canvas]]
* [[FGCanvas]]
* [[Howto:Create a 2D drawing API for FlightGear]]
* [[Howto:Use a Camera View in an Instrument]]

| heading6 = To be ported
| content6 =
* [[Navigation display]] {{Progressbar|70}}
* [[Map]] {{Progressbar|60}}

| heading7 = Obsolete (deprecated by the Canvas)
| content7 =
* [[Complex Glass Cockpit Avionics]]
* [[OpenGL GUI RESOURCES]]

}}<includeonly>{{main other|[[Category:Canvas]][[Category:Core development projects]]}}
{{howto other|[[Category:Canvas]][[Category:Howto]]}}</includeonly><noinclude>{{Informative template|1=
== Usage ==
Add the template to the top of the article text.
<nowiki>{{Canvas Navigation}}</nowiki>

Adding the template to an page in the main namespace, the article namespace, or the howto namespace will add [[:Category:Canvas]] to the page. In addition [[:Category:Howto]] will be added to articles in the howto namespace, and [[:Category:Core development projects]] will be added to articles in the main namespace.

}}

[[Category:Navigation templates]]
[[Category:Canvas]]
</noinclude>

File:Dialog-info.png

2014-06-23T14:21:51Z

TheTom:

=={{int:filedesc}}==
{{Information
|description={{en|1=Humanity info icon.}}
|date=2014-06-23 16:03:24
|source=https://launchpad.net/humanity
|author=Daniel Foré, K.Vishnoo Charan Reddy, Jonian Guveli
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{GPL}}

[[Category:Messagebox icons]]

File:Dialog-error.png

2014-06-23T14:21:18Z

TheTom:

=={{int:filedesc}}==
{{Information
|description={{en|1=Humanity error icon.}}
|date=2014-06-23 16:03:25
|source=https://launchpad.net/humanity
|author=Daniel Foré, K.Vishnoo Charan Reddy, Jonian Guveli
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{GPL}}

[[Category:Messagebox icons]]

File:Dialog-question.png

2014-06-23T14:21:11Z

TheTom:

=={{int:filedesc}}==
{{Information
|description={{en|1=Humanity question icon.}}
|date=2014-06-23 16:03:24
|source=https://launchpad.net/humanity
|author=Daniel Foré, K.Vishnoo Charan Reddy, Jonian Guveli
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{GPL}}

[[Category:Messagebox icons]]

File:Dialog-error.png

2014-06-23T14:18:56Z

TheTom: User created page with UploadWizard

File:Dialog-question.png

2014-06-23T14:18:39Z

TheTom: User created page with UploadWizard

File:Dialog-info.png

2014-06-23T14:18:27Z

TheTom: User created page with UploadWizard

List of Nasal extension functions

2014-06-20T22:45:37Z

TheTom: md5

{{Incomplete|The accuracy of this article or section may be compromised due to recent changes in the source code, please help us update this article by incorporating the [http://mapserver.flightgear.org/git/?p=flightgear;a=blob;f=src/Scripting/NasalSys.cxx#l707 latest extension functions]}}
{{Template:Nasal Navigation}}

== Nasal Core Library ==

For a list of functions implemented in C, that are available to Nasal implementations in general, see [http://plausible.org/nasal/lib.html]. Note that only the <tt>thread</tt>, <tt>io</tt>, <tt>math</tt>, and <tt>utf8</tt> libraries are currently included in SimGear.

== FlightGear's Extension Functions ==

=== <tt>cmdarg()</tt> ===
cmdarg() is a mechanism to pass arguments to a nasal script (wrapped in properties) instead of "normal" function parameters. Note that cmdarg() should be primarily used in Nasal code embedded in XML files and should be considered depreciated otherwise (see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html]).

cmdarg() will keep working in (joystick) XML-'''bindings''' and on the top-level of embedded Nasal scripts (i.e. dialog and animation XML files).

As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see [[$FG_ROOT]]/Nasal/props.nas) for example:

<syntaxhighlight lang="nasal">
print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())
</syntaxhighlight>

The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:

<syntaxhighlight lang="nasal">
setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);
</syntaxhighlight>

Use of cmdarg() outside of XML-bindings won't cause an error, but (still) return the last cmdarg() property. This just won't be the listened-to property anymore, but whatever the last legitimate cmdarg() user set. Most of the time it will be the property root of a joystick binding.

Don't make any assumptions and use cmdarg() only in one of these cases:

* binding: returns root of this binding's property branch. Needed for accessing an axis' value: cmdarg().getNode("setting").getValue()

* dialog xml files: returns root of that file's property branch in memory. This can be used to let embedded Nasal change the dialog (e.g. clear and build lists) before the final layout is decided

* animation xml files: returns root of this model's place in /ai/models/ when used as AI/MP model. Examples: /ai/models/multiplayer[3], /ai/models/tanker[1], etc.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg14164.html |title=multiplayer generic properties |date=8 December 2007 |author=Melchior Franz}}</ref>

* AI aircraft XML files

* remotely invoking Nasal code by setting properties using the built-in telnet daemon (RPC)<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00150.html |title=Calling FG functions via network interface |author=Melchior Franz |date=2 January 2006}}</ref><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00336.html |title=Calling FG functions via network interface |author=Melchior Franz |date=7 January 2006}}</ref>.

'''In all cases, the cmdarg() call must not be delayed until later using settimer() or setlistener(). Because later it'll again return some unrelated property!
'''

=== <tt>fgcommand()</tt> ===

Runs an internal "fgcommand", see [[Bindings]] for a full list of available items (since they are most often used in bindings for input devices). The first argument is the name of the command (e.g. "property-interpolate") and the second is a props.Node object or its ghost which is the "argument" to the fgcommand. (This ensures that fgcommands are universal since props.Node/SGPropertyNode objects can really be accessed from anywhere in FlightGear.) Each fgcommand returns 1 if it succeeded or 0 if it failed.

The profiling related fgcommands '''profiler-start''' and '''profiler-stop''' are documented at [[Built-in Profiler]].

=== <tt>addcommand()</tt> ===

Add a fgcommand which can be used like a regular fgcommand (global scope, etc.). First argument is the name, second is the function to run. Note that this fgcommand will always return true! Inside the callback/function one can use either cmdarg() to retrieve the arguments or use the first argument passed to the function (since they will be the same).

=== <tt>removecommand()</tt> ===

As you can guess, there's also a removecommand() function which will remove '''any''' command – even those implemented in C++! As such it can be very dangerous and remove core functionality, so use with caution.

=== <tt>print()</tt> ===
Concatenates an arbitrary number of arguments to one string, appends a new-line, and prints it to the terminal. Returns the number of printed characters.

<syntaxhighlight lang="nasal">
print("Just", " a ", "test");
</syntaxhighlight>

=== <tt>logprint()</tt> ===

Similar, but the first argument is reserved for number specifying the priority (i.e. matching a sgDebugPriority object: 1 for bulk, 2 for debug, 3 for info, and 4 for warn). Also see <tt>printlog()</tt> in globals.nas: it does essentially the same but with named levels ("bulk", etc.). (The latter relies on <tt>print()</tt>, however, and does not make use of the sophistication of <tt>sglog</tt> in dealing with source file and line number.)

=== <tt>getprop()</tt> ===

Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized to a value yet.

<syntaxhighlight lang="nasal">
getprop(<path> [, <path>, [...]]);
</syntaxhighlight>

Several arguments will be added together to produce a path, with numeric arguments specifying indexes (as of FlightGear 3.1), so
<syntaxhighlight lang="nasal">
getprop("canvas/by-index", "texture", 1, "name");
</syntaxhighlight>
is the same as:
<syntaxhighlight lang="nasal">
getprop("canvas/by-index/texture[1]/name");
</syntaxhighlight>

Example:

<syntaxhighlight lang="nasal">
print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");
for (var i=0; i < 10; i += 1) {
print("View ", i, "'s name is: ", getprop("/sim/view", i, "name"));
}
</syntaxhighlight>

=== <tt>setprop()</tt> ===
Sets a property value for a given node path string. Returns 1 on success or 0 if the property could not be set (i.e. was read-only).

<syntaxhighlight lang="nasal">
setprop(<path> [, <path>, [...]], <value>);
</syntaxhighlight>

All arguments but the last are concatenated to a path string, like getprop() above. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.

Examples:

<syntaxhighlight lang="nasal">
setprop("/sim/current-view/view-number", 2);
setprop("/controls", "engines/engine[0]", "reverser", 1);
</syntaxhighlight>

'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> has to be erased using the props namespace helper, like this:

<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>

=== <tt>interpolate()</tt> ===
Give the value from a value or a source node to a destination node in given time.

<syntaxhighlight lang="nasal">
interpolate(<path>, <value>, <time>);
</syntaxhighlight>

Examples:
<syntaxhighlight lang="nasal">
interpolate("controls/switches/nav-lights-pos", 1, 0.25); # After 25ms, nav-lights-pos = 1
interpolate("controls/gear/brake-left-pos", getprop("controls/gear/brake-left"), 1); # After 1s, brake-left-pos = brake-left
</syntaxhighlight>

=== <tt>settimer()</tt> ===
Runs a function after a given simulation time (default) or real time in seconds.

<syntaxhighlight lang="nasal">
settimer(<function>, <time> [, <realtime=0>]);
</syntaxhighlight>

The first object is a function object (ie, "func { ... }"). Note that this is different from a function call (ie, "func ( ... )"). If you don't understand what this means, just remember to always enclose the first argument in any call to settimer with the word "func" and braces "{ }", and it will always work. For instance, if you want print the words "My result" in five seconds, use this code:

<syntaxhighlight lang="nasal">
settimer ( func { print ( "My result"); }, 5);
</syntaxhighlight>

Inside the braces of the func object you can put any valid Nasal code, including a function call. In fact, if you want to call a function with certain values as arguments, the way to do it is to turn it into a function object by enclosing it with a func{}, for example:

<syntaxhighlight lang="nasal">
myarg1="My favorite string";
myarg2=432;
settimer ( func { myfunction ( myarg1, myarg2); }, 25);
</syntaxhighlight>

The third argument is optional and defaults to 0, which lets the time argument be interpreted as "seconds simulation time". In this case the timer doesn't run when FlightGear is paused. For user interaction purposes (measuring key press time, displaying popups, etc.) one usually prefers real time.

<syntaxhighlight lang="nasal">
# simulation time example
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }
settimer(copilot_annoyed, 10);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
# real time example
var popdown = func ( tipArg ) {
fgcommand("dialog-close", tipArg);
}

var selfStatusPopupTip = func (label, delay = 10, override = nil) {
var tmpl = props.Node.new({
name : "PopTipSelf", modal : 0, layout : "hbox",
y: 140,
text : { label : label, padding : 6 }
});
if (override != nil) tmpl.setValues(override);

popdown(tipArgSelf);
fgcommand("dialog-new", tmpl);
fgcommand("dialog-show", tipArgSelf);

currTimerSelf += 1;
var thisTimerSelf = currTimerSelf;

# Final argument 1 is a flag to use "real" time, not simulated time
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);
}
</syntaxhighlight>

[[Nasal scripting language#settimer loops|More information about using the settimer function to create loops.]]

=== <tt>maketimer()</tt> (2.11+) ===

As of 2.11, there is a new API for making a timer that allows more control over what happens in a timer – as opposed to setting one and forgetting about it.

<syntaxhighlight lang="nasal">
var timer = maketimer(<interval>, <function>)
var timer = maketimer(<interval>, <self>, <function>)
</syntaxhighlight>

<syntaxhighlight lang="nasal">
timer.start()
timer.stop()
timer.restart(<interval>)
timer.singleShot [read/write]
timer.isRunning [read-only]
</syntaxhighlight>

<syntaxhighlight lang="nasal">
# create timer with 1 second interval
var timer = maketimer(1.0, func {
print('timer called');
}
);
# start the timer (with 1 second inverval)
timer.start();
# restart timer with 4 second interval
timer.restart(4);

# fire one single time in 6 seconds
timer.singleShot = 1;
timer.restart(6);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
var Tooltip = {
new: func
{
var m = {
parents: [Tooltip]
}
m._hideTimer = maketimer(1.0, m, Tooltip._hideTimeout);
m._hideTimer.singleShot = 1;

return m;
},
run: func
{
if( !me._hideTimer.isRunning )
me._hideTimer.start();
}
_hideTimeout: func
{
print('_hideTimeout');
}
};
</syntaxhighlight>

=== <tt>geodinfo()</tt> ===
Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.

<syntaxhighlight lang="nasal">
var lat = getprop("/position/latitude-deg");
var lon = getprop("/position/longitude-deg");
var info = geodinfo(lat, lon);

if (info != nil) {
print("the terrain under the aircraft is at elevation ", info[0], " m");
if (info[1] != nil)
print("and it is ", info[1].solid ? "solid ground" : "covered by water");
}
</syntaxhighlight>

A full data set looks like this:

<syntaxhighlight lang="nasal">
debug.dump(geodinfo(lat, lon));

# outputs
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1,
rolling_friction : 1.5 } ]
</syntaxhighlight>

Note that geodinfo is a *very* CPU intensive operation, particularly in FG 2.4.0 and earlier, so use sparingly ([http://forum.flightgear.org/viewtopic.php?f=4&p=135044#p135044 forum discussion here]).

=== airportinfo() ===
Function for retrieval of airport/runway information.
Usage:

<syntaxhighlight lang="nasal">
var apt = airportinfo("KHAF"); # get info about KHAF
var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon
var apt = airportinfo(); # get info about apt closest to aircraft
</syntaxhighlight>

The command debug.dump(airportinfo("KHAF")) outputs this:

<syntaxhighlight lang="nasal">
{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,
runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,
lon : -122.5010889999999, lat : 37.513831, stopway1 : 0, width : 45.72,
threshold2 : 232.5624, heading : 138.1199999999999, length : 1523.0856 } },
elevation : 20.42159999999999, id : "KHAF", name : "Half Moon Bay" }
</syntaxhighlight>

That is: a hash with elements lat/lon/elev/id/name/has_metar for the airport, and a hash with runways, each of which consists of lat/lon/length/width/heading/threshold[12]/stopway[12]. Only one side of each runway is listed -- the other can easily be deduced.

=== Positioned Object Queries ===

Several functions exist to query the navigation database of 'positioned' objects, i.e items with a defined location in the simulation world. (These objects all inherit from <tt>FGPositioned</tt> internally). The functions return either one, or a vector, of wrapped Nasal objects. These are efficient, but unlike a hash they cannot simply be <tt>debug.dump()</tt> to view all their members and methods.

When the query functions take a position, the default value is the current aircraft location. An alternative location can be supplied by passing two number (lat, lon), a Geo.Coord object, or any positioned object or waypoint retrieved from another query.

;findAirportsWithinRange()
: Find all airports within a specified range (in NM) of the current position or explicit position
;findAirportsByICAO()
: Find airports matching a complete or partial ICAO code. In particular this can search for all airports starting with a two or three letter prefix.
;navinfo()
: Return a list of navaids near a location by type and ident. Type should be 'fix', 'vor', 'ndb', 'dme'
;findNavaidsWithinRange()
: Search for navaids within a particular range (in NM), optionally limited by type. This provides a 'find the closest ILS' function
;findNavaidByFrequency()
: find the closest navaid (of a particular type) matching an exact frequency
;findNavaidsByFrequency()
: find all the navaids matching a particular frequency and optional type, sorted by distance from the search location.

All positioned objects returned by the above methods have the following members:
;id
: Identifier - ICAO code for airports, published ident for navaids and fixes
;lon
: degrees longitude
;lat
: degrees latitude

Depending on type, the following members are also available:
;name
: the full name of the airport or navaid if one is defined
;elevation
: the ASL elevation of the object in feet

For navaids, the following members are available:
;frequency
: the navaid frequency in kHz
;type
: the navaid type as a string: vor, dme, loc, ils, ndb
;course
: the degrees course associated with the navaid, for localiser and ILS stations

=== <tt>history() </tt> (3.1+) ===

Function to expose flight history as aircraft.history()

<syntaxhighlight lang="nasal">
var hist = aircraft.history();

# get history of aircraft position/orientation collapsing
# nodes with a distance smaller than the given minimum
# edge legth
debug.dump( hist.pathForHistory(<minimum-edge-length-meter>) );
</syntaxhighlight>

=== <tt>flightplan()</tt> ===

Function to retrieve the active flight-plan object, or load a flight plan from a file path.

Usage:
<syntaxhighlight lang="nasal">
var fp = flightplan();
var fp = flightplan('/some/path/to/a/flightplan.xml');
</syntaxhighlight>

In advance of converting the Map and NavDisplay to use the [[Canvas]], James has improved the "flightplan()" extension function of the [[Nasal]] scripting interpreter to expose the full route-path vector for each flight plan leg as a vector on the leg.

<syntaxhighlight lang="nasal">
var fp = flightplan();
for (var i=0; i<fp.getPlanSize(); i += 1)
{
var leg = fp.getWP(i);
debug.dump(leg.path());
}
</syntaxhighlight>

=== <tt>systime()</tt> ===
Returns epoch time (time since 1972/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.

<syntaxhighlight lang="nasal">
#benchmarking example:
var start = systime();
how_fast_am_I(123);
var end = systime();
print("took ", end - start, " seconds");
</syntaxhighlight>

=== <tt>carttogeod()</tt> ===
Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.

<syntaxhighlight lang="nasal">
var geod = carttogeod(-2737504, -4264101, 3862172);
print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);

# outputs
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776
</syntaxhighlight>

=== <tt>geodtocart()</tt> ===
Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.

<syntaxhighlight lang="nasal">
var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)
print("x=", cart[0], " y=", cart[1], " z=", cart[2]);

# outputs
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495
</syntaxhighlight>

=== <tt>parsexml()</tt> ===

This function is an interface to the built-in [http://expat.sourceforge.net/ Expat XML parser]. It takes up to five arguments. The first is a mandatory absolute path to an XML file, the remaining four are optional callback functions, each of which can be nil (which is also the default value).

<syntaxhighlight lang="nasal">
var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);

<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash
<end-elem> ... called for every ending tag with one argument: the tag name
<data> ... called for every piece of data with one argument: the data string
<pi> ... called for every "processing information" with two args: target and data string

<ret> ... the return value is nil on error, and the <path> otherwise
</syntaxhighlight>

Example:

<syntaxhighlight lang="nasal">
var start = func(name, attr) {
print("starting tag ", name);
foreach (var a; keys(attr))
print("\twith attribute ", a, "=", attr[a]);
}
var end = func(name) { print("ending tag ", name) }
var data = func(data) { print("data=", data) }
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }
parsexml("/tmp/foo.xml", start, end, data, pi);
</syntaxhighlight>

=== <tt>resolvepath()</tt> ===

SimGear features its own [[Resolving Paths|path resolving framework]] that takes a relative path and returns an absolute path, checking from base directories such as [[$FG_ROOT]], [[$FG_HOME]], [[$FG_AIRCRAFT]], and the current aircraft directory (<tt>/sim/aircraft-dir</tt>). This function in Nasal takes a path string and returns the absolute path or an empty string if the path couldn't be resolved.

Example:

<syntaxhighlight lang="nasal">
var guess_path = func(path...) {
var path_concat = string.join(path, "/");
var file_path = resolvepath(path_concat);
if (file_path == "") die("Path not found: "~path_concat);
return file_path;
}
</syntaxhighlight>

=== HTTP module (2.99+) ===

Get remote data using the HTTP.

==== <tt>http.load()</tt> ====

Load resource identified by its URL into memory.

<syntaxhighlight lang="nasal">
var request = http.load(<url>);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
http.load("http://example.com/test.txt")
.done(func(r) print("Got response: " ~ r.response));
</syntaxhighlight>

==== <tt>http.save()</tt> ====

Save resource to a local file.

<syntaxhighlight lang="nasal">
var request = http.save(<url>, <file_path>);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
http.save("http://example.com/test.png", getprop('/sim/fg-home') ~ '/cache/test.png')
.fail(func print("Download failed!"))
.done(func(r) print("Finished request with status: " ~ r.status ~ " " ~ r.reason))
.always(func print("Request complete (fail or success)"));
</syntaxhighlight>

=== <tt>rand()</tt> ===

Return a random number as generated by <tt>sg_random</tt>.

=== <tt>srand()</tt> ===

Seed the random number generator based upon the current time. Returns 0.

=== <tt>md5()</tt> (3.1+) ===

Get the md5 hash of a string.

<syntaxhighlight lang="nasal">
var hash = md5(<str>);
</syntaxhighlight>

=== <tt>abort()</tt> ===

Wrapper for the C++ library abort() function – i.e. it just aborts the process without regard to what's happening. For exiting (gracefully) from FlightGear use the fgcommand "exit" instead.

<references/>

User:TheTom

2014-05-21T13:04:33Z

TheTom:

[[Category:FlightGear Core developers]]
[[Category:Developer Plans]]

{{User
|name = Thomas (TheTom)
|location = Austria}}

== Development plan ==

=== GUI / render ===

* Canvas based GUI {{Pending}}
** Create dialogs {{Done}} and widgets {{Pending}} from Nasal
** Handle keyboard input {{Not done}}
** Parse current gui and menu xml files {{Not done}}
* Canvas based HUD {{Pending}}
** Nasal API/framwork {{Pending}}
** Parse HUD xml files {{Not done}}
** Use Canvas GUI for 2D HUD {{Not done}}
** object placements for 3D HUD? {{Pending}}
*** Take care of projection/moving head {{Pending}}
* Canvas (API/General)
** Rotate map children according to map heading {{Pending}}

=== Animation ===

* Improved/advanced animations
** [[Tracking animation]] {{Done}}
* Blender animation/basic fdm exporter {{Pending}}

=== Simulation / systems ===

* Generic sytem building blocks {{Pending}}
** Allow to use conditions/expressions/property-rules/etc. to simulate any type of system (eg. electric, hydraulic,...) and especially take care to be able to build reusable building blocks.
** Unify/cleanup expression parser {{Not done}}
** Generic APU {{Pending}}
** Generic electrical system {{Pending}}
* Generic VDGS {{Pending}}
* MCDU/FMS/AMU framework {{Pending}}
* Blender system exporter {{Not done}}

=== Aircraft / Scenery ===

* [[Lockheed Martin C-130J Super Hercules]] {{Pending}}
* [http://www.flightgear.org/forums/viewtopic.php?f=5&t=18475 Flughafen Graz-Thalerhof (LOWG)] {{Pending}}

=== General ===

* Respect XDG directories (and environment variables) {{Not done}}

List of Nasal extension functions

2014-05-10T22:44:44Z

TheTom: aircraft.history: describe parameter

{{Incomplete|The accuracy of this article or section may be compromised due to recent changes in the source code, please help us update this article by incorporating the [http://mapserver.flightgear.org/git/?p=flightgear;a=blob;f=src/Scripting/NasalSys.cxx#l707 latest extension functions]}}
{{Template:Nasal Navigation}}

== Nasal Core Library ==

For a list of functions implemented in C, that are available to Nasal implementations in general, see [http://plausible.org/nasal/lib.html]. Note that only the <tt>thread</tt>, <tt>io</tt>, <tt>math</tt>, and <tt>utf8</tt> libraries are currently included in SimGear.

== FlightGear's Extension Functions ==

=== <tt>cmdarg()</tt> ===
cmdarg() is a mechanism to pass arguments to a nasal script (wrapped in properties) instead of "normal" function parameters. Note that cmdarg() should be primarily used in Nasal code embedded in XML files and should be considered depreciated otherwise (see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html]).

cmdarg() will keep working in (joystick) XML-'''bindings''' and on the top-level of embedded Nasal scripts (i.e. dialog and animation XML files).

As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see [[$FG_ROOT]]/Nasal/props.nas) for example:

<syntaxhighlight lang="nasal">
print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())
</syntaxhighlight>

The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:

<syntaxhighlight lang="nasal">
setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);
</syntaxhighlight>

Use of cmdarg() outside of XML-bindings won't cause an error, but (still) return the last cmdarg() property. This just won't be the listened-to property anymore, but whatever the last legitimate cmdarg() user set. Most of the time it will be the property root of a joystick binding.

Don't make any assumptions and use cmdarg() only in one of these cases:

* binding: returns root of this binding's property branch. Needed for accessing an axis' value: cmdarg().getNode("setting").getValue()

* dialog xml files: returns root of that file's property branch in memory. This can be used to let embedded Nasal change the dialog (e.g. clear and build lists) before the final layout is decided

* animation xml files: returns root of this model's place in /ai/models/ when used as AI/MP model. Examples: /ai/models/multiplayer[3], /ai/models/tanker[1], etc.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg14164.html |title=multiplayer generic properties |date=8 December 2007 |author=Melchior Franz}}</ref>

* AI aircraft XML files

* remotely invoking Nasal code by setting properties using the built-in telnet daemon (RPC)<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00150.html |title=Calling FG functions via network interface |author=Melchior Franz |date=2 January 2006}}</ref><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00336.html |title=Calling FG functions via network interface |author=Melchior Franz |date=7 January 2006}}</ref>.

'''In all cases, the cmdarg() call must not be delayed until later using settimer() or setlistener(). Because later it'll again return some unrelated property!
'''

=== <tt>fgcommand()</tt> ===

Runs an internal "fgcommand", see [[Bindings]] for a full list of available items (since they are most often used in bindings for input devices). The first argument is the name of the command (e.g. "property-interpolate") and the second is a props.Node object or its ghost which is the "argument" to the fgcommand. (This ensures that fgcommands are universal since props.Node/SGPropertyNode objects can really be accessed from anywhere in FlightGear.) Each fgcommand returns 1 if it succeeded or 0 if it failed.

The profiling related fgcommands '''profiler-start''' and '''profiler-stop''' are documented at [[Built-in Profiler]].

=== <tt>addcommand()</tt> ===

Add a fgcommand which can be used like a regular fgcommand (global scope, etc.). First argument is the name, second is the function to run. Note that this fgcommand will always return true! Inside the callback/function one can use either cmdarg() to retrieve the arguments or use the first argument passed to the function (since they will be the same).

=== <tt>removecommand()</tt> ===

As you can guess, there's also a removecommand() function which will remove '''any''' command – even those implemented in C++! As such it can be very dangerous and remove core functionality, so use with caution.

=== <tt>print()</tt> ===
Concatenates an arbitrary number of arguments to one string, appends a new-line, and prints it to the terminal. Returns the number of printed characters.

<syntaxhighlight lang="nasal">
print("Just", " a ", "test");
</syntaxhighlight>

=== <tt>logprint()</tt> ===

Similar, but the first argument is reserved for number specifying the priority (i.e. matching a sgDebugPriority object: 1 for bulk, 2 for debug, 3 for info, and 4 for warn). Also see <tt>printlog()</tt> in globals.nas: it does essentially the same but with named levels ("bulk", etc.). (The latter relies on <tt>print()</tt>, however, and does not make use of the sophistication of <tt>sglog</tt> in dealing with source file and line number.)

=== <tt>getprop()</tt> ===

Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized to a value yet.

<syntaxhighlight lang="nasal">
getprop(<path> [, <path>, [...]]);
</syntaxhighlight>

Several arguments will be added together to produce a path, with numeric arguments specifying indexes (as of FlightGear 3.1), so
<syntaxhighlight lang="nasal">
getprop("canvas/by-index", "texture", 1, "name");
</syntaxhighlight>
is the same as:
<syntaxhighlight lang="nasal">
getprop("canvas/by-index/texture[1]/name");
</syntaxhighlight>

Example:

<syntaxhighlight lang="nasal">
print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");
for (var i=0; i < 10; i += 1) {
print("View ", i, "'s name is: ", getprop("/sim/view", i, "name"));
}
</syntaxhighlight>

=== <tt>setprop()</tt> ===
Sets a property value for a given node path string. Returns 1 on success or 0 if the property could not be set (i.e. was read-only).

<syntaxhighlight lang="nasal">
setprop(<path> [, <path>, [...]], <value>);
</syntaxhighlight>

All arguments but the last are concatenated to a path string, like getprop() above. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.

Examples:

<syntaxhighlight lang="nasal">
setprop("/sim/current-view/view-number", 2);
setprop("/controls", "engines/engine[0]", "reverser", 1);
</syntaxhighlight>

'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> has to be erased using the props namespace helper, like this:

<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>

=== <tt>interpolate()</tt> ===
Give the value from a value or a source node to a destination node in given time.

<syntaxhighlight lang="nasal">
interpolate(<path>, <value>, <time>);
</syntaxhighlight>

Examples:
<syntaxhighlight lang="nasal">
interpolate("controls/switches/nav-lights-pos", 1, 0.25); # After 25ms, nav-lights-pos = 1
interpolate("controls/gear/brake-left-pos", getprop("controls/gear/brake-left"), 1); # After 1s, brake-left-pos = brake-left
</syntaxhighlight>

=== <tt>settimer()</tt> ===
Runs a function after a given simulation time (default) or real time in seconds.

<syntaxhighlight lang="nasal">
settimer(<function>, <time> [, <realtime=0>]);
</syntaxhighlight>

The first object is a function object (ie, "func { ... }"). Note that this is different from a function call (ie, "func ( ... )"). If you don't understand what this means, just remember to always enclose the first argument in any call to settimer with the word "func" and braces "{ }", and it will always work. For instance, if you want print the words "My result" in five seconds, use this code:

<syntaxhighlight lang="nasal">
settimer ( func { print ( "My result"); }, 5);
</syntaxhighlight>

Inside the braces of the func object you can put any valid Nasal code, including a function call. In fact, if you want to call a function with certain values as arguments, the way to do it is to turn it into a function object by enclosing it with a func{}, for example:

<syntaxhighlight lang="nasal">
myarg1="My favorite string";
myarg2=432;
settimer ( func { myfunction ( myarg1, myarg2); }, 25);
</syntaxhighlight>

The third argument is optional and defaults to 0, which lets the time argument be interpreted as "seconds simulation time". In this case the timer doesn't run when FlightGear is paused. For user interaction purposes (measuring key press time, displaying popups, etc.) one usually prefers real time.

<syntaxhighlight lang="nasal">
# simulation time example
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }
settimer(copilot_annoyed, 10);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
# real time example
var popdown = func ( tipArg ) {
fgcommand("dialog-close", tipArg);
}

var selfStatusPopupTip = func (label, delay = 10, override = nil) {
var tmpl = props.Node.new({
name : "PopTipSelf", modal : 0, layout : "hbox",
y: 140,
text : { label : label, padding : 6 }
});
if (override != nil) tmpl.setValues(override);

popdown(tipArgSelf);
fgcommand("dialog-new", tmpl);
fgcommand("dialog-show", tipArgSelf);

currTimerSelf += 1;
var thisTimerSelf = currTimerSelf;

# Final argument 1 is a flag to use "real" time, not simulated time
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);
}
</syntaxhighlight>

[[Nasal scripting language#settimer loops|More information about using the settimer function to create loops.]]

=== <tt>maketimer()</tt> (v. 2.11+) ===

As of 2.11, there is a new API for making a timer that allows more control over what happens in a timer – as opposed to setting one and forgetting about it.

<syntaxhighlight lang="nasal">
var timer = maketimer(<interval>, <function>)
var timer = maketimer(<interval>, <self>, <function>)
</syntaxhighlight>

<syntaxhighlight lang="nasal">
timer.start()
timer.stop()
timer.restart(<interval>)
timer.singleShot [read/write]
timer.isRunning [read-only]
</syntaxhighlight>

<syntaxhighlight lang="nasal">
# create timer with 1 second interval
var timer = maketimer(1.0, func {
print('timer called');
}
);
# start the timer (with 1 second inverval)
timer.start();
# restart timer with 4 second interval
timer.restart(4);

# fire one single time in 6 seconds
timer.singleShot = 1;
timer.restart(6);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
var Tooltip = {
new: func
{
var m = {
parents: [Tooltip]
}
m._hideTimer = maketimer(1.0, m, Tooltip._hideTimeout);
m._hideTimer.singleShot = 1;

return m;
},
run: func
{
if( !me._hideTimer.isRunning )
me._hideTimer.start();
}
_hideTimeout: func
{
print('_hideTimeout');
}
};
</syntaxhighlight>

=== <tt>geodinfo()</tt> ===
Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.

<syntaxhighlight lang="nasal">
var lat = getprop("/position/latitude-deg");
var lon = getprop("/position/longitude-deg");
var info = geodinfo(lat, lon);

if (info != nil) {
print("the terrain under the aircraft is at elevation ", info[0], " m");
if (info[1] != nil)
print("and it is ", info[1].solid ? "solid ground" : "covered by water");
}
</syntaxhighlight>

A full data set looks like this:

<syntaxhighlight lang="nasal">
debug.dump(geodinfo(lat, lon));

# outputs
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1,
rolling_friction : 1.5 } ]
</syntaxhighlight>

Note that geodinfo is a *very* CPU intensive operation, particularly in FG 2.4.0 and earlier, so use sparingly ([http://forum.flightgear.org/viewtopic.php?f=4&p=135044#p135044 forum discussion here]).

=== airportinfo() ===
Function for retrieval of airport/runway information.
Usage:

<syntaxhighlight lang="nasal">
var apt = airportinfo("KHAF"); # get info about KHAF
var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon
var apt = airportinfo(); # get info about apt closest to aircraft
</syntaxhighlight>

The command debug.dump(airportinfo("KHAF")) outputs this:

<syntaxhighlight lang="nasal">
{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,
runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,
lon : -122.5010889999999, lat : 37.513831, stopway1 : 0, width : 45.72,
threshold2 : 232.5624, heading : 138.1199999999999, length : 1523.0856 } },
elevation : 20.42159999999999, id : "KHAF", name : "Half Moon Bay" }
</syntaxhighlight>

That is: a hash with elements lat/lon/elev/id/name/has_metar for the airport, and a hash with runways, each of which consists of lat/lon/length/width/heading/threshold[12]/stopway[12]. Only one side of each runway is listed -- the other can easily be deduced.

=== Positioned Object Queries ===

Several functions exist to query the navigation database of 'positioned' objects, i.e items with a defined location in the simulation world. (These objects all inherit from <tt>FGPositioned</tt> internally). The functions return either one, or a vector, of wrapped Nasal objects. These are efficient, but unlike a hash they cannot simply be <tt>debug.dump()</tt> to view all their members and methods.

When the query functions take a position, the default value is the current aircraft location. An alternative location can be supplied by passing two number (lat, lon), a Geo.Coord object, or any positioned object or waypoint retrieved from another query.

;findAirportsWithinRange()
: Find all airports within a specified range (in NM) of the current position or explicit position
;findAirportsByICAO()
: Find airports matching a complete or partial ICAO code. In particular this can search for all airports starting with a two or three letter prefix.
;navinfo()
: Return a list of navaids near a location by type and ident. Type should be 'fix', 'vor', 'ndb', 'dme'
;findNavaidsWithinRange()
: Search for navaids within a particular range (in NM), optionally limited by type. This provides a 'find the closest ILS' function
;findNavaidByFrequency()
: find the closest navaid (of a particular type) matching an exact frequency
;findNavaidsByFrequency()
: find all the navaids matching a particular frequency and optional type, sorted by distance from the search location.

All positioned objects returned by the above methods have the following members:
;id
: Identifier - ICAO code for airports, published ident for navaids and fixes
;lon
: degrees longitude
;lat
: degrees latitude

Depending on type, the following members are also available:
;name
: the full name of the airport or navaid if one is defined
;elevation
: the ASL elevation of the object in feet

For navaids, the following members are available:
;frequency
: the navaid frequency in kHz
;type
: the navaid type as a string: vor, dme, loc, ils, ndb
;course
: the degrees course associated with the navaid, for localiser and ILS stations

=== <tt>history() </tt> (3.1+) ===

Function to expose flight history as aircraft.history()

<syntaxhighlight lang="nasal">
var hist = aircraft.history();

# get history of aircraft position/orientation collapsing
# nodes with a distance smaller than the given minimum
# edge legth
debug.dump( hist.pathForHistory(<minimum-edge-length-meter>) );
</syntaxhighlight>

=== <tt>flightplan()</tt> ===

Function to retrieve the active flight-plan object, or load a flight plan from a file path.

Usage:
<syntaxhighlight lang="nasal">
var fp = flightplan();
var fp = flightplan('/some/path/to/a/flightplan.xml');
</syntaxhighlight>

In advance of converting the Map and NavDisplay to use the [[Canvas]], James has improved the "flightplan()" extension function of the [[Nasal]] scripting interpreter to expose the full route-path vector for each flight plan leg as a vector on the leg.

<syntaxhighlight lang="nasal">
var fp = flightplan();
for (var i=0; i<fp.getPlanSize(); i += 1)
{
var leg = fp.getWP(i);
debug.dump(leg.path());
}
</syntaxhighlight>

=== <tt>systime()</tt> ===
Returns epoch time (time since 1972/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.

<syntaxhighlight lang="nasal">
#benchmarking example:
var start = systime();
how_fast_am_I(123);
var end = systime();
print("took ", end - start, " seconds");
</syntaxhighlight>

=== <tt>carttogeod()</tt> ===
Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.

<syntaxhighlight lang="nasal">
var geod = carttogeod(-2737504, -4264101, 3862172);
print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);

# outputs
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776
</syntaxhighlight>

=== <tt>geodtocart()</tt> ===
Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.

<syntaxhighlight lang="nasal">
var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)
print("x=", cart[0], " y=", cart[1], " z=", cart[2]);

# outputs
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495
</syntaxhighlight>

=== <tt>parsexml()</tt> ===

This function is an interface to the built-in [http://expat.sourceforge.net/ Expat XML parser]. It takes up to five arguments. The first is a mandatory absolute path to an XML file, the remaining four are optional callback functions, each of which can be nil (which is also the default value).

<syntaxhighlight lang="nasal">
var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);

<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash
<end-elem> ... called for every ending tag with one argument: the tag name
<data> ... called for every piece of data with one argument: the data string
<pi> ... called for every "processing information" with two args: target and data string

<ret> ... the return value is nil on error, and the <path> otherwise
</syntaxhighlight>

Example:

<syntaxhighlight lang="nasal">
var start = func(name, attr) {
print("starting tag ", name);
foreach (var a; keys(attr))
print("\twith attribute ", a, "=", attr[a]);
}
var end = func(name) { print("ending tag ", name) }
var data = func(data) { print("data=", data) }
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }
parsexml("/tmp/foo.xml", start, end, data, pi);
</syntaxhighlight>

=== <tt>resolvepath()</tt> ===

SimGear features its own [[Resolving Paths|path resolving framework]] that takes a relative path and returns an absolute path, checking from base directories such as [[$FG_ROOT]], [[$FG_HOME]], [[$FG_AIRCRAFT]], and the current aircraft directory (<tt>/sim/aircraft-dir</tt>). This function in Nasal takes a path string and returns the absolute path or an empty string if the path couldn't be resolved.

Example:

<syntaxhighlight lang="nasal">
var guess_path = func(path...) {
var path_concat = string.join(path, "/");
var file_path = resolvepath(path_concat);
if (file_path == "") die("Path not found: "~path_concat);
return file_path;
}
</syntaxhighlight>

=== HTTP module (v. 2.99+) ===

Get remote data using the HTTP.

==== <tt>http.load()</tt> ====

Load resource identified by its URL into memory.

<syntaxhighlight lang="nasal">
var request = http.load(<url>);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
http.load("http://example.com/test.txt")
.done(func(r) print("Got response: " ~ r.response));
</syntaxhighlight>

==== <tt>http.save()</tt> ====

Save resource to a local file.

<syntaxhighlight lang="nasal">
var request = http.save(<url>, <file_path>);
</syntaxhighlight>

<syntaxhighlight lang="nasal">
http.save("http://example.com/test.png", getprop('/sim/fg-home') ~ '/cache/test.png')
.fail(func print("Download failed!"))
.done(func(r) print("Finished request with status: " ~ r.status ~ " " ~ r.reason))
.always(func print("Request complete (fail or success)"));
</syntaxhighlight>

=== <tt>rand()</tt> ===

Return a random number as generated by <tt>sg_random</tt>.

=== <tt>srand()</tt> ===

Seed the random number generator based upon the current time. Returns 0.

=== <tt>abort()</tt> ===

Wrapper for the C++ library abort() function – i.e. it just aborts the process without regard to what's happening. For exiting (gracefully) from FlightGear use the fgcommand "exit" instead.

<references/>

User:TheTom

2014-04-01T14:03:10Z

TheTom:

[[Category:FlightGear Core developers]]
[[Category:Developer Plans]]

{{User
|name = Thomas (TheTom)
|location = Austria}}

== Development plan ==

=== GUI / render ===

* Canvas based GUI {{Pending}}
** Create dialogs {{Done}} and widgets {{Pending}} from Nasal
** Handle keyboard input {{Not done}}
** Parse current gui and menu xml files {{Not done}}
* Canvas based HUD {{Pending}}
** Nasal API/framwork {{Pending}}
** Parse HUD xml files {{Not done}}
** Use Canvas GUI for 2D HUD {{Not done}}
** object placements for 3D HUD? {{Pending}}
*** Take care of projection/moving head {{Pending}}

=== Animation ===

* Improved/advanced animations
** [[Tracking animation]] {{Done}}
* Blender animation/basic fdm exporter {{Pending}}

=== Simulation / systems ===

* Generic sytem building blocks {{Pending}}
** Allow to use conditions/expressions/property-rules/etc. to simulate any type of system (eg. electric, hydraulic,...) and especially take care to be able to build reusable building blocks.
** Unify/cleanup expression parser {{Not done}}
** Generic APU {{Pending}}
** Generic electrical system {{Pending}}
* Generic VDGS {{Pending}}
* MCDU/FMS/AMU framework {{Pending}}
* Blender system exporter {{Not done}}

=== Aircraft / Scenery ===

* [[Lockheed Martin C-130J Super Hercules]] {{Pending}}
* [http://www.flightgear.org/forums/viewtopic.php?f=5&t=18475 Flughafen Graz-Thalerhof (LOWG)] {{Pending}}

Changelog 3.2

2014-04-01T13:59:57Z

TheTom: No need to mention separate states. The main reason was pushing all attributes on the attribute stack. This was safe but not fast^^

{{draft|changelog|This changelog is currently being written for the FlightGear 3.2 release. To see what is being worked on, check out [[Changelog 3.2.0]].
Feel free to help! If you are aware of any FlightGear related changes, please add them to the changelog. It's a good idea to check [[:Category:Changes_after_3.00|the newsletters since the last release]], and the git commit history.
To view the changelog for the most recent release, please see [[Changelog 3.00]].
We also encourage people to help by translating the changelog and appreciate all contributions, however please keep in mind that this changelog is not yet final!

}}

==Upcoming FlightGear Changelog==



=== Major enhancements in this release ===

'''Surface Light Effects & OpenSceneGraph 3.2'''

Stuart committed a change that brings surface lights, including VASI/PAPI/taxi/runway etc. into the xml-defined Effects framework. Kudos to Tim Moore for his original Effects work - it made it very straightforward to enhance with support for point sprites and a custom texture generator required.

The relevant effect is data/Effects/surface-lights.eff. It should allow development of ALS and Rembrandt variants.

Stuart also replaced some OSG color/normal binding calls that were removed in OSG3.2.0, apparently because they were slow. So, if your
build fails, please check you've got a recent OSG build installed.

'''Core'''
* [[Reset & re-init]] is merged and now enabled

'''Aircraft Modeling'''
* extra 500
* Tu-154B2 version 3.1
* additional aircraft have started adopting Gijs' [[NavDisplay]]

'''JSBSim'''
* ground effects (see newsletter 02/2014)

'''Environment Rendering'''

'''Performance'''
* F-JJTH and Stuart have started working on using osg::Simplifier [https://gitorious.org/fg/simgear/commit/3429e0072103a8c90d8e456f1f6b711099851225]: http://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/CAP3ntysifK34TxANKUj1s4Of_dJRg7dvJ74Gbko4zXVFHdV-YQ%40mail.gmail.com/#msg32016452

'''Misc/Uncategorized'''
* AIModels use PagedLOD
* Optimise NavCache airport query
* osg::Switch for masking scenery rendering
* Torsten's metar work, newradio, mongoose httpd
* HTTP: improve handling of connection errors
* [[FGCamera]] (external addon, not yet reviewed/committed as of 03/2014)

''' Usability '''

''' Internationalization '''

''' Scenery '''

'''Canvas System'''

FlightGear's fully scriptable 2D rendering system now includes improved APIs for creating maps and navigation displays amongst many other improvements. People no longer need to have programming experience to add a working ND to their aircraft, it can now be all done by copying and pasting 30 lines of text and customizing a few properties. The so called MapStructure back-end handles efficient updating of all ND layers transparently.

* Tom has pushed an update to git (simgear) which removes a lot of unneeded OpenGL state changes for Canvas paths. Depending on the GPU/driver this can lead to quite a noticeable performance improvement. For example, he was able to get from ~120ms down to ~45ms [http://forum.flightgear.org/viewtopic.php?f=71&t=16984&p=204730#p204730].
* Hooray is working on adding shader support to Canvas {{Progressbar|30}}
* Gijs is currently working on additional projections as part of {{Issue|550}}
* The [[MapStructure]] back-end used by the [[NavDisplay]] now supports symbol instancing, so that performance is improved
* MapStructure-based layers can now be customized and styled
* Tom added support for button/modifiers (mouse handling) [http://wiki.flightgear.org/index.php?title=Canvas_Event_Handling&curid=10777&diff=68569&oldid=68422]
* CanvasImage now supports the ''http://'' protocol for dynamically retrieving raster images. See the renamed [[Canvas_Image#src|src attribute]] (''file'' is now deprecated).

'''Nasal Scripting'''

* getprop()/setprop() arguments (those that form a path) can now be numeric to specify a index, so:
<syntaxhighlight lang="nasal">
getprop("canvas/by-index", "texture", 1, "name");
</syntaxhighlight>
: is now the same as:
<syntaxhighlight lang="nasal">
getprop("canvas/by-index/texture[1]/name");
</syntaxhighlight>
: (see [https://gitorious.org/fg/flightgear/commit/5eee5e42ae4f5cf56283b3bf5a3be46efc2b51c4 merge request 54] and [https://gitorious.org/fg/flightgear/commit/34ed79e5f88ffdfc5e651a1fe3e639cb8f4d3353 actual commit])
'''Documentation'''

'''Highlighted new and improved aircraft'''

'''Other'''

'''Bug fixes'''

* See [http://code.google.com/p/flightgear-bugs/issues/list?can=1&q=Milestone%3D3.0 our bugtracker] for an extensive, yet incomplete, list of the bugs fixed in this release.

[[Category:FlightGear changelogs]]

FlightGear Newsletter April 2014

2014-04-01T13:55:19Z

TheTom:

{{newsletter}}
{{TOC_right|limit=2}}

{{Newsletter being written}}
== Development news ==
Note to all contributors: Please also copy your newsletter additions to the changelog for the upcoming release: [[Next Changelog]].

=== Canvas GUI Progress ===

=== Random Buildings ===

=== Project Rembrandt ===
A number of Mac users have been reporting issues related to running [[Project Rembrandt]] (deferred rendering/shadows) on Mac OSX with ATI/AMD GPUS, we are now looking for Mac users to provide feedback on running Rembrandt on Mac OSX, required information includes errors and warnings shown during startup/runtime, but also screen shots showing any issues. Please see: [[Project Rembrandt#Mac Issues]].

=== Canvas System ===

Tom has updated FlightGear 3.1 to remove a lot of unneeded OpenGL state changes. Depending on the GPU/driver this can lead to quite a noticeable performance improvement. For example, he was able to get from ~120ms down to ~45ms [http://forum.flightgear.org/viewtopic.php?f=71&t=16984&p=204730#p204730].

=== High Level Architecture ===

=== Usability Improvements ===

=== Getting involved as a programmer ===
Unfortunately, most of the active FG developers are currently very overstretched in terms of the areas that they have ownership of, which is affecting how much can actually be done. Fundamentally we need more core devs.

If you are interested in contributing as a core developer, please see [[Howto:Start core development]].

If you interested in other developing, i.e. not C++ but [[Nasal]] scripting and/or XML, there are some articles listed at [[:Category:Popular Community Requests]] that have been suggested, but not fully or partially implemented, and are "mentored efforts". That means that the community is looking for a hand in implementing them -- help from ''you'' -- but will also have more experienced developers willing to help you, for example by having tailored tutorials or even code snippets written for you. As mentioned in each page, please get in touch if you would like to help with one of those projects. In comparison to C/C++, Nasal is simpler and easier to learn quickly. It also doesn't require recompiling, which means that you can test and develop changes with a standard FlightGear release, i.e. off of the main download page. As long as you can run FlightGear, you can also run Nasal code and contribute. Many tutorials covering a wide range of projects are listed at [[Nasal]], so if you know a programming/scripting language already, or would like to try something new, go ahead: read, write, try and get involved! When it comes to Nasal scripting, playing around with different tutorials and code snippets is more important than being an experienced coder.

Of course, you're also free to work on whatever you want -- FlightGear as a community-driven doesn't tell people what to do, but welcomes any contributions from anybody, as long as they have acceptable quality and are free to be licensed under the GNU GPL. So if you have something you would like to contribute back to FlightGear, please get in touch! (Preferably using Gitorious for larger merge requests, and the forums or (core-) developer's mailing list to inform the developers of what you want to contribute back.) Changes contributed 6-8 weeks before a release will usually appear in the next release, so your changes can be spread across the world.

== Release ChangeLog ==
This section lists changes committed this month that will be available in the next release, these will be copied to the release changelog shortly before a release (for each month), so that we hopefully get a comprehensive list of new features.

== Interview with a contributor (NAME) ==
''In each edition we have an interview with a contributor. Suggestions for possible questions are available on [[interview questions]], you are invited to come up with new questions and interview ideas obviously! Anyone is free to write an interview (with him-/herself or others) for next month's newsletter! If you'd like to help interview a contributor or get interviewed, please do consider adding yourself to the [[list of interview volunteers]]! To keep this going and less awkward, we are currently trying to come up with the convention that former interviewees become next month's interviewers.''

* How long have you been involved in FlightGear?
* What are your major interests in FlightGear?
* What project are you working on right now?
* What do you plan on doing in the future?
* Are you happy with the way the FlightGear project is going?
* What do you enjoy most about developing for FlightGear?
* Are there any "hidden features" you have worked on in FlightGear that new users may miss?
* What advice can you give to new developers who want to get started on their first aircraft/new feature/Nasal script?

More questions are being collected here: [[Interview questions]].

Stay tuned for next month's interview, featuring FlightGear contributor XXXXXXXX

== Nasal for newbies ==

== New software tools and projects ==

== FlightGear addons and mods ==

== In the hangar ==

=== New aircraft ===

=== Updated aircraft ===

=== Liveries ===

== Scenery corner ==
=== Airports ===

== Aircraft of the month ==
== Airport of the month ==
== Screenshot of the month ==

== Suggested flights ==
== Aircraft reviews ==

== Wiki updates ==
=== Translators required ===
{|
|[[File:en.gif]]
|The FlightGear Wiki still needs help for translating it into various languages. If you are interested in making the FlightGear Wiki multi-language then start at [[Help:Translate]].
|-
|[[File:de.gif]]
|Das FlightGear Wiki benötigt immer noch Hilfe bei der Übersetzung in verschiedene Sprachen. Wenn Du Interesse daran hast, das FlightGear Wiki Mehrsprachig zu machen, dann fang doch mit [[:de:Help:Übersetzen|Help:Übersetzen]] an.
|-
|[[File:nl.gif]]
|De FlightGear Wiki kan nog steed hulp gebruiken bij het vertalen van artikelen. Als je interesse hebt om de wiki meertalig te maken, raden we je aan om een kijkje te nemen bij [[:nl:Help:Vertalen|Help:Vertalen]].
|-
|[[File:es.gif]]
|La FlightGear wiki todavía necesita ayuda para traducirla a varios lenguajes. Si estás interesado en hacer la FlightGear wiki multilingüe, entonces comienza en [[:es:Help:Traducir|Help:Traducir]].
|}

== Community news ==
=== FlightGear on YouTube ===

=== New tutorials and screencasts ===
=== Forum news ===
=== Multiplayer ===
=== Virtual airlines ===
=== FlightGear events ===

== Useful links ==
== And finally ... ==
=== Contributing ===

{{Volunteer Intro|mode=showlogo}}



=== YASim looking for a new maintainer ===

{{cquote|There are some pending merge requests to add some Yasim features, but we have an issue that since none of the current C++ developers own, or are experts in Yasim, we're reluctant to be the person who merges such changes, and potentially introduces subtle regressions.

Obviously this is chicken-and-egg, since no one can become expert enough in the code to become a maintainer :)

So, I'm more than happy to apply patches *providing* I can be convinced they are sane+reasonable from a pure code perspective (happy to help with that, too,
if people are new to C++), and providing we have some assurance that a representative sample of yasim aircraft are unchanged or improved by the patch.
Suggestions for that means in practice, are most welcome!

Otherwise I worry, given the nature of the solver, we'll keep optimising the solver for some aircraft, and making other existing aircraft worse - until someone tests them, and announced that they're no longer working.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg23986.html
|title=YASim and documentation
|author=James Turner |date= Fri, 05 Oct 2012 03:54:43 -0700}}</ref>|James Turner}}

{{cquote|I am still broadly happy to answer questions if posed (as long as I remember enough to come up with a meaningful answer). Just cc: me if you do, because my
latencies here are measured in weeks.
Bugs can always be fixed. What YASim needs is a maintainer, not really expertise per se. The latter comes from the former.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg23986.html
|title=YASim and documentation
|author=Andy Ross |date= Fri, 05 Oct 2012 03:54:43 -0700}}</ref>|Andy Ross}}

<references/>

=== Call for volunteers ===
* The Terragear maintainers are looking for volunteers to help with development on the next world scenery project. If you've ever wondered how a full 3D model of earth can be generated from raw data, now is your chance. See the plan at [[World Scenery 3.0 roadmap]].
* The [[Target4Today]] team is looking for volunteers to help improving FlightGear's combat support

=== Did you know ===

[[Category:FlightGear Newsletter]]


[[Category:Changes after 3.00]]

Template:Canvas Navigation

2014-03-21T19:28:46Z

TheTom: dead link

{{forum|71|Canvas}}
{{sidebar
| name = Canvas Navigation
| title = Canvas - the FlightGear 2D drawing API
| contentstyle= text-align: left;

| content1 =
* [[Canvas]] - Main Page
* [[Canvas Development]]
* [[Canvas GUI]]
* [[Canvas Widgets]]
* [[Canvas Maps]]

| heading2 = Frameworks
| content2 =
{{Canvas Frameworks|mode=navbar}}

| heading3 = Tutorials
| content3 =
* [[Howto:Adding a canvas to a GUI dialog]]
* [[Howto:Add a 2D canvas instrument to your aircraft]]
* [[Howto:Parsing 2D Instruments using the Canvas]]
* [[Howto:Creating fullscreen Canvas applications]]
* [[Howto:Use SVG inside a Canvas]]
* [[Howto:Canvas applications as Nasal submodules]]
* [[Howto:Using raster images and nested canvases]]

* [[Howto:Creating a Canvas graph widget]]
* [[Canvas HUD]]
| heading4 = Reference
| content4 =
* [[Canvas Element]]
** [[Canvas Group|Group]]
** [[Canvas Image|Image]]
** [[Canvas Map|Map]]
** [[Canvas Path|Path]]
** [[Canvas Text|Text]]
* [[Canvas Readme]]
* [[Canvas Nasal API]]
* [[Canvas - Event_Handling|Event Handling]]
| heading5 = Related
| content5 =
* [[Canvas Properties]]
* [[Unifying the 2D rendering backend via canvas]]
* [[FGCanvas]]
* [[Howto:Create a 2D drawing API for FlightGear]]
* [[Howto:Use a Camera View in an Instrument]]

| heading6 = To be ported
| content6 =
* [[Navigation display]] {{Progressbar|70}}
* [[Map]] {{Progressbar|60}}

| heading7 = Obsolete (depreciated by the Canvas)
| content7 =
* [[Complex Glass Cockpit Avionics]]
* [[OpenGL GUI RESOURCES]]

}}<includeonly>{{main other|[[Category:Canvas]][[Category:Core development projects]]}}
{{howto other|[[Category:Canvas]][[Category:Howto]]}}</includeonly><noinclude>{{Informative template|1=
== Usage ==
Add the template to the top of the article text.
<nowiki>{{Canvas Navigation}}</nowiki>

Adding the template to an page in the main namespace, the article namespace, or the howto namespace will add [[:Category:Canvas]] to the page. In addition [[:Category:Howto]] will be added to articles in the howto namespace, and [[:Category:Core development projects]] will be added to articles in the main namespace.

}}

[[Category:Navigation templates]]
[[Category:Canvas]]
</noinclude>