Canvas EFIS framework: Difference between revisions

Jump to navigation Jump to search

Canvas EFIS framework (view source)

Revision as of 21:35, 9 February 2020

8,870 bytes added ,  9 February 2020
m
no edit summary
No edit summary
mNo edit summary
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Stub}}
{{Template:Canvas Navigation}}
{{Template:Canvas Navigation}}


Line 376: Line 374:




=== EICAS / ECAM message system ===
=== EICAS message system ===
to be written
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.
For each message a corresponding property can be defined that controls whether or not the message is shown.
Alternatively, a message can be shown or hidden via the Nasal methods (see also the HOWTO section for examples and best practices).
 
==== Methods of class MessageSystem ====
===== new() =====
{{Nasal doc
|syntax = new(page_length, prop_path);
|text = Creates a new message system.
|param1 = page_length
|param1text = Maximum page length. Page length can be changed at runtime but not exceed this initial value.
|param2 = prop_path
|param2text = Property path, some config and data of the message system will be put here.
}}
 
===== setPowerProp() =====
{{Nasal doc
|syntax = setPowerProp(prop_path);
|text = Sets a listener to the "power switch" property. Will call init() if property changes to true.
|param1 = prop_path
|param1text = Path to a bool property representing the EFIS power state.
}}
 
===== addMessageClass() =====
{{Nasal doc
|syntax = addMessageClass(class_name, paging, color = nil);
|text = Sets the number of lines per page.
|param1 = lines
|param1text = Number of lines per page
}}
 
===== addMessages() =====
{{Nasal doc
|syntax = addMessages(class, messages);
|text = Add message definitions to a class. Setup listeners according to message definitions that call setMessage() accordingly.
|param1 = class
|param1text = Class identifier returned by addMessageClass()
|param2 = messages
|param2text = Vector of message definitions. See below for format.
}}
 
===== addAuralAlerts() =====
{{Nasal doc
|syntax = addAuralAlerts(alert_hash);
|text = Set aural alert configuration hash
|param1 = alert_hash
|param1text = Hash; aural_name: {path: "myAircraft/Sounds", file: "sound.wav", volume: 1.0 }
}}
 
===== setMessage() =====
{{Nasal doc
|syntax = setMessage(class, msg_id, visible=1);
|text = Show or hide a message, optional trigger aural alert on show. Does nothing if message is already in desired state.
|param1 = class
|param1text = Class identifier returned by addMessageClass()
|param2 = msg_id
|param2text = see getMessageID()
|param3 = visible
|param3text = bool; 0 = hide, otherwise show
}}
 
===== init() =====
{{Nasal doc
|syntax = init();
|text = Used on power up to check for active messages. Enables sound queue for aural alerts.
}}
 
===== hasUpdate() =====
{{Nasal doc
|syntax = hasUpdate();
|text = Returns update flag.
}}
 
===== setPageLength() =====
{{Nasal doc
|syntax = setPageLength(length);
|text = Change page length. Length cannot exceed initial page length (see new())
|param1 = length
|param1text = New number of lines per page.
}}
 
===== getPageLength() =====
{{Nasal doc
|syntax = getPageLength();
|text = Returns current page length.
}}
 
===== getFirstUpdateIndex() =====
{{Nasal doc
|syntax = getFirstUpdateIndex();
|text = Returns the index of the first line that has changed.
}}
 
===== getActiveMessages() =====
{{Nasal doc
|syntax = getActiveMessages();
|text = Returns message queue and clears the hasUpdate flag.
}}
 
===== getMessageID() =====
{{Nasal doc
|syntax = getMessageID(class, msg_text);
|text = Returns numeric id for a message in given class.
|param1 = class
|param1text = Class identifier returned by addMessageClass()
|param2 = msg_text
|param2text = Message string to search for.
}}
 
===== disableMessage() =====
{{Nasal doc
|syntax = disableMessage(class, msg_id);
|text = Inhibit message (or all messages in class if no msg_id is given).
|param1 = class
|param1text = Class identifier returned by addMessageClass()
|param2 = msg_id
|param2text = see getMessageID()
}}
 
===== enableMessage() =====
{{Nasal doc
|syntax = enableMessage(class, msg_id);
|text = Re-enable message (or all messages in class if no id is given).
|param1 = class
|param1text = Class identifier returned by addMessageClass()
|param2 = msg_id
|param2text = see getMessageID()
}}
 
'''-- following methods are for message output on a canvas --'''
 
===== setCanvasGroup() =====
{{Nasal doc
|syntax = setCanvasGroup(group);
|text = Set an existing canvas group to create text elements on.
|param1 = group
|param1text = A valid canvas group element
}}
 
===== createCanvasTextLines() =====
{{Nasal doc
|syntax = createCanvasTextLines(left, top, line_spacing, font_size);
|text = Show or hide a message, optional trigger aural alert on show. Does nothing if message is already in desired state.
|param1 = left, top
|param1text = Position of text element.
|param2 = line_spacing
|param2text = see getMessageID()
|param3 = font_size
|param3text = Font size.
}}
 
===== createPageIndicator() =====
{{Nasal doc
|syntax = createPageIndicator(left, top, font_size, format_string = nil);
|text = Creates a text element for a page indicator on the canvas group set with setCanvasGroup().
|param1 = left, top
|param1text = Position of text element
|param2 = font_size
|param2text = Font size.
|param3 = format_string
|param3text = Optional printf format string, defaults to "Page %2d/%2d"
}}
 
===== updateCanvas() =====
{{Nasal doc
|syntax = updateCanvas();
|text = Call this regularly to update text lines on canvas with the content of the message queue.
}}
 
===== updatePageIndicator() =====
{{Nasal doc
|syntax = updatePageIndicator(current, total);
|text = Updates the page indicator text element.
|param1 = current
|param1text = Currently displayed page.
|param2 = total
|param2text = Total number of pages.
}}
 
 


==== Format for message definitions ====
==== 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).
''prop'' shall be used if
# the visibility of a message depends on only one property
# this property does NOT change frequently
The optional ''condition'' element reqires ''prop'' and is again a hash where you can define up to four compare values.
For each existing key a listener to ''prop'' will be created performing the selected comparision.
It is up to the developer to provide a reasonable configuration here.
The optional ''aural'' element can be any key of the aural configuration hash passed to MessageSystem.addAuralAlerts(). If the
<nowiki>
{
    msg: "Message Text",
    prop: "/some/bool/trigger", # optional
    aural: "sound_name",        # optional
    condition: {                # optional
        eq: "foo",
        ne: "bar",
        lt: 21, # "less than",
        gt: 42, # "greater than",
    },
}
# example:
var EICASMessages = [
    {msg: "APU FIRE", prop: "engines/engine[2]/on-fire", aural: "firebell"},
    {msg: "AC 1 AUTOXFER", prop: "systems/AC/system[1]/serviceable", condition: {eq: 0}},
    {msg: "AC BUS 1", prop: "systems/AC/outputs/bus1", condition: {lt: 100}},
    {msg: "ELT ON", prop: ""},
];
</nowiki>
==== Class MessageClass ====
Helper class for MessageSystem. Stores configuration data for a message class.


==== Class Pager ====
==== Class Pager ====
==== Class MessageClass ====
Helper class for MessageSystem.
==== Class MessageSystem ====
The pager class takes a vector of messages and splits it into pages (sub vectors of defined length).
It can be configured via the Nasal methods described below or via some properties on the fly.
 
'''Config nodes'''
{| class="wikitable"
|-
! property name !! Type and access !! Description
|-
| page_length || (INT, r/w)|| maximum number of lines per page.
|-
| page || (INT, r/w)|| currently selected page.
|-
| pages || (INT, r/o)|| number of pages according to last run of the page() method.
|}
 
===== new() =====
{{Nasal doc
|syntax = new(page_length, prop_path);
|text = Configure the nasal file to load.
|param1 = page_length
|param1text = Maximum lines per page.
|param2 = prop_path
|param2text = Property base path; pager configuration nodes will be created under this path.
}}
 
===== page() =====
{{Nasal doc
|syntax = page(lines);
|text = Return lines of current page; sticky messages will not be paged.
|param1 = lines
|param1text = Vector of messages
}}
 
===== pageChanged() =====
{{Nasal doc
|syntax = pageChanged();
|text = Return the page-changed flag and resets it to false, so calling this method again will return false unless another page has been selected in the meantime.
}}
 
===== setPageLength() =====
{{Nasal doc
|syntax = setPageLength(lines);
|text = Update the value of the page_length node (the number of lines per page).
|param1 = lines
|param1text = Number of lines per page
}}
 
===== setPage() =====
{{Nasal doc
|syntax = setPage(page);
|text = Update the value of page node used by page() to return the right lines.
|param1 = page
|param1text = Selected page
}}
 
===== getPageCount() =====
Returns total number of pages, according to last run of page()
 
===== getCurrentPage() =====
Returns current page, according to last run of page()


== HOWTO and Examples ==
== HOWTO and Examples ==
to be written
to be written / reference implementation in CRJ700 familiy to be published after framework is published.
Jsb
250

edits

Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/121456...121461"

Navigation menu