Canvas GUI API

Canvas - the FlightGear 2D drawing API
Canvas - Main Page Canvas News - for the latest developments Shiva Alternatives - ongoing work for Core Profile support Canvas FAQs - frequently asked questions Canvas - Getting started Canvas Development (core) Canvas Troubleshooting (core) Canvas Sandbox (core) PUI2Canvas (PUI/XML Parser) Canvas GUI Canvas Widgets Canvas Maps Canvas Snippets
RFC
Canvas Instancing Howto:New Canvas Execution Model Canvas SVG Canvas Popout Windows Canvas Scenery Overlays
Frameworks
Canvas Map API (soon deprecated!) Canvas MapStructure Canvas MapStructure Layers MapStructure Snippets Canvas Radar Canvas Animation Framework (WIP) Canvas Plotting Framework (WIP) Canvas MFD Framework Canvas ND Framework Canvas PFD Framework Canvas MCDU Framework Canvas EFB Framework Canvas Wrappers Canvas Glass Cockpit Efforts
Tutorials
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 Canvas HUD Howto:Project 3D to 2D coordinates on desktop canvas
Reference
Canvas Element Group Image Map Path Text Canvas Nasal API MessageBox Layout System Canvas GUI API Canvas draw library Event Handling
Related
Canvas Properties Unifying the 2D rendering backend via canvas Howto:Use a Camera View in an Instrument Howto:Extending Canvas to support rendering 3D models Howto:Extending Canvas to support MathGL
To be ported
Navigation display Map FGCanvas Canvas Nasal/JavaScript Subset
Deprecated by Canvas
Complex Glass Cockpit Avionics
(click on headings to toggle)

gui.nas implements the classes gui, WindowButton and Window. It loads nasal files from $FGROOT/Nasal/canvas/gui for widgets and styles.

See inside the current (Git) API here.

For the Canvas API see Canvas Nasal API

gui

Container class. Stores widgets and the focused window (if any).

gui.Widget

Template class that implements common methods, used by widget classes Button, CheckBox, Lable, LineEdit, ScrollArea

new: func(derived)

derived class, e.g. gui.widgets.Button

_windowFocus: func

returns: bool, focused

Config

Trivial container class to store (key,value) pairs

new: func(cfg)

cfg: hash, used to initialize the config object data

returns: object

get: func(key, default = nil)

returns: the value for key or default if that one is nil

set: func(key, value)

returns: me

DefaultStyle

This class stors widget factories

new: func(name, name_icon_theme)

parameters are forwarded to gui.Style.new constructor

returns:' object

DefaultStyle.widgets

At the time of writing there are the following widgets:

button, checkbox, lable, line-edit, scroll-area

They have the following common methods:

new: func(parent, cfg)

parent: parent canvas element (e.g. group) cfg: a config object

update: func(model)

model canvas.Window - strange name... no idea why somebody named it model

Aparently this method is called on events like mouse move/click so each widget can show an appropriate reaction.

DefaultStyle.widgets.line-edit

A one line text input field

DefaultStyle.widgets.scroll-area

_newScroll: func(el, orient)

private

_updateScrollMetrics: func(model, dir)

private

WindowButton

This class manages a button implemented as canvas.image element.

new(parent, name)

parent:

name: string, used to identify the WindowButton and load decoration image files from $FGROOT/gui/style/<StyleName>/decoration/

e.g. for a button named "close", you should have files close_focused_normal.png, close_focused_prelight.png, close_focused_pressed.png, close_unfocused_normal.png, close_unfocused_prelight.png, close_unfocused_pressed.png

protected _onStateChange()

Different images are sourced e.g. for hover, focus etc. according to the active style.

Window

new: func(size, type = nil, id = nil)

size: vector [x,y], initial size of the window

type: ? set property "type"

id: ? used in var ghost = _newWindowGhost(id);

Constructor to create a new instance of canvas.Window

returns: Window object

del: func

Destructor to clean up. Canvas will not be deleted if it has other "placements"

setTitle: func(title)

title: string

Set property "title" (e.g. text on the titlebar)

returns: Window object (me)

createCanvas: func()

Create the canvas to be used for this Window, add placement and mousedown listener.

returns: The new canvas

setCanvas: func(canvas_)

canvas_: canvas object

Replace canvas of this window with canvas_ and remove onRezize method so window cannot be resized anymore.

getCanvas: func(create = 0)

create: bool, create canvas for this window if it does not exist

returns: canvas object of this window

getCanvasDecoration: func()

returns: canvas object of the window decoration (?)

setLayout: func(l)

l (?)

Call me._ghost.setLayout(l);

returns: Window object (me)

setFocus: func

Set this window focused and tell gui class about it.

returns: Window object (me)

clearFocus: func

Clear focus from this window and tell gui class about it.

returns: Window object (me)

setPosition: func (arg...)

arg: either a vector [x, y] or two parameters x,y

Set window position to (x,y) where (0,0) is (left, top)

returns: Window object (me)

setSize: func(arg...)

arg: either a vector [width, height] or two parameters width, height

Set content-size to width, height and call me.onResize if exists.

returns: Window object (me)

move: func

arg: either a vector [x, y] or two parameters x,y

Moves window by x to the right and y down.

returns: Window object (me)

raise: func()

Update z-index and call setFocus()

returns: Window object (me)

onResize: func()

Update canvas size and view to Window.content-size

returns: Window object (me) or nil if window has no canvas.

Private methods The following methods should NOT be called directly, they shall be used ONLY by the methods above.

_onStateChange: func

Used in setFocus(), clearFocus() and _updateDecoration().

_propCallback: func(child, mode)

Used in Window.new (m is the window object under creation):

arg is a vector [child, listener_node, mode, is_child_event]

setlistener(m._node, func m._propCallback(arg[0], arg[2]), 0, 2);

_handlePositionAbsolute: func(child, mode, name, index)

used only in _propCallback

_updatePos: func(index, name)

used only in _handlePositionAbsolute

_handleResize: func(child, name)

used only in _propCallback

_updateDecoration: func()

used only in _propCallback

_resizeDecoration: func()

used by _propCallback and _updateDecoration

Dialog (depricated)

canvas.Dialog is deprectated! Use canvas.Window instead.