This is the base class for objects representing the status lines, which are the one-line text messages that appear near the bottom of the main playfield window. Each status line rotates through a series of messages that can be customized by the user in the setting.
There are three status lines in PinballY, each one represented by a system-defined Javascript object of class StatusLine. Each one can be accessed through a property of the mainWindow.statusLines object, which is just a wrapper object containing the references to the individual status line objects in its properties.
You can use methods of these objects to access and change the messages displayed in the corresponding on-screen status areas.
Each StatusLine object is an event target, so you can use the standard event methods (on(), off(), etc) to add and remove event listeners. See EventTarget.
The StatusLine objects serve as the target for the following event types:
statusLine.add(text, index): Inserts a new message. text is a string giving the new message text to add. This is the source text of the message, so it can contain substitution variables that will be replaced with their current values each time the message is displayed on-screen. index is an optional integer giving the position in the list at which to insert the new message. 0 inserts the new message before the first existing message, 1 inserts it before the existing second message, and so on. If this is omitted or is out of range, the new message is inserted at the end of the current list.
statusLine.getCur(): Returns the index of the item currently being displayed. Returns -1 if there are no items in the list.
The current message index can change between Javascript event handler invocations, but it can't change within a single event handler.
statusLine.getText(): Returns an array representing all of the messages in the rotation list for this status line. The array indices correspond to the index values used in the methods that operate on specific message entries (add(), remove(), etc). Each element of the array is an object with these properties:
The array is just a snapshot of the system's internal message list, so changes you make to the array or the message strings won't have any effect on what's displayed. If you want to make changes to the live display list, use the various methods that operate on it (setText(), add(), etc).
statusLine.id: A string identifying the status line:
statusLine.remove(index): Deletes an entry from the status line's message list. index is an integer giving the position of the item to remove: 0 is the first item, 1 is the second item, and so on.
statusLine.setText(index, text): Changes the source text of the item selected by the integer index value to the string text. The source text is the text before substitution variables are replaced, so this can contain variables that will be automatically replaced with current values each time the message is displayed.
The index value can range from 0 to one less than the number of items in the status line's internal message list. You can retrieve the current list with getText().
If the item is currently being displayed, the on-screen message will be immediately updated to reflect the new message.
statusLine.show(text): Displays a one-time-only message. text is the source text to display, which can include substitution variables that will be replaced with their current values.
The message isn't displayed immediately, but rather is inserted into the message list just after the current message and after any temporary messages that already follow the current message. This means that it will be displayed as soon as the current message's normal timer interval expires and the status line is ready to move on to the next message naturally. The reason that the new message is inserted after any other temporary messages already queued up is that this preserves the ordering if you display a series of temporary messages, so that the messages are displayed in the same order in which they were added. The inserted message is marked as temporary, so that it's only displayed once, and then automatically deleted from the rotation.
This function lets you display quick feedback for user actions in situations where a more intrusive message format (such as a pop-up message box) would be too heavy-weight. Status line messages don't require any user acknowledgment and are visually unobtrusive, so they're good for cases where there's no particular need to alert the user to whatever information is being displayed, but where a user who's actively watching for the information might still want to see it.