250
edits
No edit summary |
mNo edit summary |
||
(2 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Template:Canvas Navigation}} | {{Template:Canvas Navigation}} | ||
Line 376: | Line 374: | ||
=== EICAS / | === EICAS message system === | ||
to | 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 ==== | ||
==== | Helper class for 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. |
edits