Canvas GUI API

From FlightGear wiki
Jump to navigation Jump to search

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


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


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

setFixedSize: func(x, y)

setEnabled: func(enabled)

move: func(x, y)

setSize: func(w, h)

setGeometry: func(geom)

setFocus: func

clearFocus: func

listen: func(type, cb)

onRemove: func

_onStateChange: func

visibilityChanged: func(visible)

_setView: func(view)

_trigger: func(type, data = nil)

_windowFocus: func

returns: bool, focused


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


This class stors widget factories

new: func(name, name_icon_theme)

parameters are forwarded to constructor

returns:' object

createWidget: func(parent, type, cfg)


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.


setSize: func(model, w, h)

setText: func(model, text)


setSize: func(model, w, h)

setText: func(model, text)


setSize: func(model, w, h)

setText: func(model, text)

setImage: func(model, img)

setBackground: func(model, bg)

heightForWidth: func(w)

_createElement: func(name, type)

_deleteElement: func(name)


A one line text input field

setSize: func(model, w, h)

setText: func(model, text)


setColorBackground: func

_newScroll: func(el, orient)


_updateScrollMetrics: func(model, dir)



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

new(parent, name)


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.


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 (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.