Action code operators show() and String.show() allow the user to display a simple textual message in the front document window.
The message placard
The message is displayed in a placard that rises from the bottom of the window and stretches across both panes. The area shown makes the message harder to miss but does not imply it is designed for large amounts of text.
Messages are unformatted text characters only
Although a message can be passed as an attribute value or a variable, the message must consist of text characters. Images cannot be displayed, nor can the message—once passed—be code that needs further evaluating. In the latter case evaluate the expression before passing the message.
The 'text' is unicode, so it does allow for use of non-Roman scripts (e.g. Cyrillic, Japanese, Chinese, etc.—assuming suitable fonts are present), as well as emoji and character-encoded symbols.
As text is rendered plain, any source text styling (bolding, etc.) is not retained in the message rendering.
(Maximum) amount of text shown
This feature is designed for simple short messages. Text will flow across the whole width of the placard. Line breaks are honoured. The placard will show up to 4 lines of text, and the message cannot be scrolled to show additional content. Messages should thus be designed with this in mind.
Message duration
A message sent to the placard will be displayed for 5 seconds after which the placard closes. If a new message is issued before the first message is complete, the new message immediately replaces the existing message and starts a new 5 second clock.
Message queue
If a new message is sent while a message is already being displayed, the new message will be shown after the previous message is hidden. Thus there is an implicit queue, with each queue item being shown for 5 seconds until the queue is empty. The placard is lowered between successive messages which helps signal the change of message (even if the colours are not changed).
Placard background and text colour
Both message methods have a pair of optional arguments, backgroundColor and textColor to set either/both the colour of the placard and the message's text colour. The text default colour is black but this may provide insufficient contrast if a custom background colour is applied. Either colour can be specified as a string conforming to allowed colour specification methods.
The backgroundColor argument may be used on its own, with default black text:
show("Hello World","blue");
but if textColor is specified, a backgroundColor value must be passed:
show("Hello World","blue");
show("Hello World","blue", "#FFF');
Do not try this
show("Hello World",,"blue"); WRONG! Do not use
as the result is an undefined background colour (which is normally a shade of orange brown)
Considerations for use vs. logging messages
An alternative method of feedback is to use a note's $Text, as a log, and append to the content there. Bear in mind:
- placard messages are not saved. After 5 seconds of display any message is gone and not retrievable.
- if a message is long, consider if the fixed duration of 5 seconds is enough to read the message before it clears.