252
edits
m (wiki formating issue) |
mNo edit summary |
||
Line 75: | Line 75: | ||
* If an animation is triggered only by one property and that property is unlikely to change often, remove the prop / animation from the update loop and use a listener instead. The listener may read other props as needed. A listener does not consume any CPU unless the property it listens to has changed, in which case the listener function is run. | * If an animation is triggered only by one property and that property is unlikely to change often, remove the prop / animation from the update loop and use a listener instead. The listener may read other props as needed. A listener does not consume any CPU unless the property it listens to has changed, in which case the listener function is run. | ||
== Framework documentation == | == Framework API documentation == | ||
The following sections document the framework classes and their methods. | |||
== Class EFIS == | |||
This is the top level class which ties together the different parts like display units, sources and cockpit controls. | This is the top level class which ties together the different parts like display units, sources and cockpit controls. | ||
=== new() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = new(display_names, object_names, canvas_settings=nil); | |syntax = new(display_names, object_names, canvas_settings=nil); | ||
Line 93: | Line 93: | ||
}} | }} | ||
=== setPowerProp() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setPowerProp(path); | |syntax = setPowerProp(path); | ||
Line 101: | Line 101: | ||
}} | }} | ||
=== setWindowSize() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setWindowSize(window_size); | |syntax = setWindowSize(window_size); | ||
Line 109: | Line 109: | ||
}} | }} | ||
=== setDUPowerProps() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setDUPowerProps(power_props, minimum_power=0); | |syntax = setDUPowerProps(power_props, minimum_power=0); | ||
Line 119: | Line 119: | ||
}} | }} | ||
=== addSource() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addSource(efis_canvas); | |syntax = addSource(efis_canvas); | ||
Line 127: | Line 127: | ||
}} | }} | ||
=== addDisplaySwapControl() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addDisplaySwapControl(ctrl, mappings, callback=nil); | |syntax = addDisplaySwapControl(ctrl, mappings, callback=nil); | ||
Line 139: | Line 139: | ||
}} | }} | ||
=== addSourceSelector() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addSourceSelector(selected, target, sources=nil); | |syntax = addSourceSelector(selected, target, sources=nil); | ||
Line 151: | Line 151: | ||
}} | }} | ||
=== setDefaultMapping() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setDefaultMapping(mapping); | |syntax = setDefaultMapping(mapping); | ||
Line 159: | Line 159: | ||
}} | }} | ||
=== displayWindow() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = displayWindow(id); | |syntax = displayWindow(id); | ||
Line 168: | Line 168: | ||
== Class EFISCanvas == | |||
EFISCanvas manages a single canvas for you. | EFISCanvas manages a single canvas for you. | ||
It offers a bunch of little helpers to make the live of an aircraft developer easier. | It offers a bunch of little helpers to make the live of an aircraft developer easier. | ||
These helpers mostly do animation and update stuff on canvas elements in an efficient way. | These helpers mostly do animation and update stuff on canvas elements in an efficient way. | ||
=== new() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = new(name, svgfile); | |syntax = new(name, svgfile); | ||
Line 183: | Line 183: | ||
}} | }} | ||
=== getPath() === | |||
returns path of canvas | returns path of canvas | ||
=== getCanvas() === | |||
returns canvas instance | returns canvas instance | ||
=== getRoot() === | |||
returns root group of the canvas | returns root group of the canvas | ||
=== setUpdateN() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setUpdateN(node); | |syntax = setUpdateN(node); | ||
Line 200: | Line 200: | ||
}} | }} | ||
=== loadsvg() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = loadsvg(file); | |syntax = loadsvg(file); | ||
Line 208: | Line 208: | ||
}} | }} | ||
=== addUpdateFunction() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addUpdateFunction(f, interval); | |syntax = addUpdateFunction(f, interval); | ||
Line 218: | Line 218: | ||
}} | }} | ||
=== startUpdates() === | |||
Start all update timers. | Start all update timers. | ||
=== stopUpdates() === | |||
Stop all update timers. | Stop all update timers. | ||
=== getInstr() === | |||
When updating EFIS displays, there is a need to access properties under /instrumentation very often. | When updating EFIS displays, there is a need to access properties under /instrumentation very often. | ||
To avoid the rather expensive append operator ("~") and property path lookups, you should use this little helper. | To avoid the rather expensive append operator ("~") and property path lookups, you should use this little helper. | ||
Line 242: | Line 242: | ||
}} | }} | ||
=== updateTextElement() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = updateTextElement(svgkey, text, color=nil); | |syntax = updateTextElement(svgkey, text, color=nil); | ||
Line 254: | Line 254: | ||
}} | }} | ||
=== _updateClip() === | |||
private function that sets clipping for an element, if there is another element with the same name extended by "_clip". | private function that sets clipping for an element, if there is another element with the same name extended by "_clip". | ||
=== Listener factories === | |||
{{note| | {{note| | ||
The following listener factories will return a function. The general usage is | The following listener factories will return a function. The general usage is | ||
Line 269: | Line 269: | ||
==== _makeListener_showHide() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = _makeListener_showHide(svgkey, value=nil); | |syntax = _makeListener_showHide(svgkey, value=nil); | ||
Line 279: | Line 279: | ||
}} | }} | ||
==== _makeListener_rotate() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = _makeListener_rotate(svgkey, factors=nil); | |syntax = _makeListener_rotate(svgkey, factors=nil); | ||
Line 289: | Line 289: | ||
}} | }} | ||
==== _makeListener_translate() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = _makeListener_translate(svgkey, fx, fy); | |syntax = _makeListener_translate(svgkey, fx, fy); | ||
Line 301: | Line 301: | ||
}} | }} | ||
==== _makeListener_setColor() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = _makeListener_setColor(svgkey, color_true, color_false); | |syntax = _makeListener_setColor(svgkey, color_true, color_false); | ||
Line 313: | Line 313: | ||
}} | }} | ||
==== _makeListener_updateText() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = _makeListener_updateText(svgkey, format="%s", default=""); | |syntax = _makeListener_updateText(svgkey, format="%s", default=""); | ||
Line 326: | Line 326: | ||
== | == Class DisplayUnit == | ||
This class is used by the EFIS class. DisplayUnit creates and places a canvas to a 3D object specified in new(). | This class is used by the EFIS class. DisplayUnit creates and places a canvas to a 3D object specified in new(). | ||
=== new() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = new(name, canvas_settings, screen_obj, parent_obj = nil); | |syntax = new(name, canvas_settings, screen_obj, parent_obj = nil); | ||
Line 343: | Line 343: | ||
}} | }} | ||
=== setSource() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = display_unit.setSource(path); | |syntax = display_unit.setSource(path); | ||
Line 351: | Line 351: | ||
}} | }} | ||
=== setPowerSource() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = display_unit.setPowerSource(prop, min); | |syntax = display_unit.setPowerSource(prop, min); | ||
Line 365: | Line 365: | ||
}} | }} | ||
=== asWindow() === | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = display_unit.asWindow(window_size); | |syntax = display_unit.asWindow(window_size); | ||
Line 374: | Line 374: | ||
== EICAS message system == | |||
The message system decouples the update of canvas text elements (e.g. message lines) from the handling of messages. | The message system decouples the update of canvas text elements (e.g. message lines) from the handling of messages. | ||
It is configured with the necessary message classes (e.g. warnings, caution messages, status messages) and a list of all possible messages. | It is configured with the necessary message classes (e.g. warnings, caution messages, status messages) and a list of all possible messages. | ||
Line 380: | Line 380: | ||
Alternatively, a message can be shown or hidden via the Nasal methods (see also the HOWTO section for examples and best practices). | Alternatively, a message can be shown or hidden via the Nasal methods (see also the HOWTO section for examples and best practices). | ||
=== | === Class MessageSystem === | ||
==== new() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = new(page_length, prop_path); | |syntax = new(page_length, prop_path); | ||
Line 391: | Line 391: | ||
}} | }} | ||
==== setPowerProp() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setPowerProp(prop_path); | |syntax = setPowerProp(prop_path); | ||
Line 399: | Line 399: | ||
}} | }} | ||
==== addMessageClass() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addMessageClass(class_name, paging, color = nil); | |syntax = addMessageClass(class_name, paging, color = nil); | ||
Line 407: | Line 407: | ||
}} | }} | ||
==== addMessages() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addMessages(class, messages); | |syntax = addMessages(class, messages); | ||
Line 417: | Line 417: | ||
}} | }} | ||
==== addAuralAlerts() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = addAuralAlerts(alert_hash); | |syntax = addAuralAlerts(alert_hash); | ||
Line 425: | Line 425: | ||
}} | }} | ||
==== setMessage() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setMessage(class, msg_id, visible=1); | |syntax = setMessage(class, msg_id, visible=1); | ||
Line 437: | Line 437: | ||
}} | }} | ||
==== init() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = init(); | |syntax = init(); | ||
Line 443: | Line 443: | ||
}} | }} | ||
==== hasUpdate() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = hasUpdate(); | |syntax = hasUpdate(); | ||
Line 449: | Line 449: | ||
}} | }} | ||
==== setPageLength() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setPageLength(length); | |syntax = setPageLength(length); | ||
Line 457: | Line 457: | ||
}} | }} | ||
==== getPageLength() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = getPageLength(); | |syntax = getPageLength(); | ||
Line 463: | Line 463: | ||
}} | }} | ||
==== getFirstUpdateIndex() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = getFirstUpdateIndex(); | |syntax = getFirstUpdateIndex(); | ||
Line 469: | Line 469: | ||
}} | }} | ||
==== getActiveMessages() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = getActiveMessages(); | |syntax = getActiveMessages(); | ||
Line 475: | Line 475: | ||
}} | }} | ||
==== getMessageID() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = getMessageID(class, msg_text); | |syntax = getMessageID(class, msg_text); | ||
Line 485: | Line 485: | ||
}} | }} | ||
==== disableMessage() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = disableMessage(class, msg_id); | |syntax = disableMessage(class, msg_id); | ||
Line 495: | Line 495: | ||
}} | }} | ||
==== enableMessage() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = enableMessage(class, msg_id); | |syntax = enableMessage(class, msg_id); | ||
Line 507: | Line 507: | ||
'''-- following methods are for message output on a canvas --''' | '''-- following methods are for message output on a canvas --''' | ||
==== setCanvasGroup() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setCanvasGroup(group); | |syntax = setCanvasGroup(group); | ||
Line 515: | Line 515: | ||
}} | }} | ||
==== createCanvasTextLines() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = createCanvasTextLines(left, top, line_spacing, font_size); | |syntax = createCanvasTextLines(left, top, line_spacing, font_size); | ||
Line 527: | Line 527: | ||
}} | }} | ||
==== createPageIndicator() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = createPageIndicator(left, top, font_size, format_string = nil); | |syntax = createPageIndicator(left, top, font_size, format_string = nil); | ||
Line 539: | Line 539: | ||
}} | }} | ||
==== updateCanvas() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = updateCanvas(); | |syntax = updateCanvas(); | ||
Line 545: | Line 545: | ||
}} | }} | ||
==== updatePageIndicator() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = updatePageIndicator(current, total); | |syntax = updatePageIndicator(current, total); | ||
Line 557: | Line 557: | ||
=== Format for message definitions === | |||
MessageSystem.addMessages() expects a vector of message definitions. A message definition is a hash with the keys ''msg'', ''prop'', ''aural'', ''condition'' (only msg is required, the rest is optional). | MessageSystem.addMessages() expects a vector of message definitions. A message definition is a hash with the keys ''msg'', ''prop'', ''aural'', ''condition'' (only msg is required, the rest is optional). | ||
Line 591: | Line 591: | ||
|lang="nasal"}} | |lang="nasal"}} | ||
=== Class MessageClass === | |||
Helper class for MessageSystem. Stores configuration data for a message class. | Helper class for MessageSystem. Stores configuration data for a message class. | ||
=== Class Pager === | |||
Helper class for MessageSystem. | Helper class for MessageSystem. | ||
The pager class takes a vector of messages and splits it into pages (sub vectors of defined length). | The pager class takes a vector of messages and splits it into pages (sub vectors of defined length). | ||
Line 611: | Line 611: | ||
|} | |} | ||
==== new() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = new(page_length, prop_path); | |syntax = new(page_length, prop_path); | ||
Line 621: | Line 621: | ||
}} | }} | ||
==== page() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = page(lines); | |syntax = page(lines); | ||
Line 629: | Line 629: | ||
}} | }} | ||
==== pageChanged() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = pageChanged(); | |syntax = pageChanged(); | ||
Line 635: | Line 635: | ||
}} | }} | ||
==== setPageLength() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setPageLength(lines); | |syntax = setPageLength(lines); | ||
Line 643: | Line 643: | ||
}} | }} | ||
==== setPage() ==== | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = setPage(page); | |syntax = setPage(page); | ||
Line 651: | Line 651: | ||
}} | }} | ||
==== getPageCount() ==== | |||
Returns total number of pages, according to last run of page() | Returns total number of pages, according to last run of page() | ||
==== getCurrentPage() ==== | |||
Returns current page, according to last run of page() | Returns current page, according to last run of page() | ||
== HOWTO and Examples == | == HOWTO and Examples == | ||
to be written / reference implementation in CRJ700 familiy to be published after framework is published. | to be written / reference implementation in CRJ700 familiy to be published after framework is published. |
edits