Created: 15-07-2021
Last update: 15-07-2021
Back Previous Next

Beginners howto 12 - popping up a notice

There is only one proper way to do this, and it works in FKiSS: make a graphics file bearing the message, convert it to a cel, define the cel in a cnf, unmap the cel under initialize(), and map the cel when the message needs to be shown, then unmap it either by clicking on it or via an alarm set after the map() action.

Having said that, KiSS creators have used syntax added in higher versions, which was not necessarily meant for that:

First, debug(), part of the FKiSS1b set of commands. From debug()'s habit of writing to the terminal in Linux, or to some other external file otherwise, it is clear that this command, as can be guessed from its name, is meant to send meaningful error messages when debugging the FKiSS code in a cnf. It will very likely never pop up a message in the KiSS viewer itself.

Added with FKiSS2, notify() does pop up in the KiSS viewer window; in PlayFKiSS, annoyingly so! It maps a message popup on top of the KiSS window, makes a jarring "error" sound, and blocks access to the viewer until clicked away. Moreover, if two or more notify() actions are put under the same action:

;@  notify("Hello!") notify("How are you?")
then the last message will be on top, that is to say, the player first sees "How are you?", clicks this message away, and then sees the "Hello!" under it. It's better to put notify() actions under alarms, and let the alarms go off several seconds after each other, so at least the player sees the messages appear in the right order.

Not only is notify() unreliable across viewers and irritating in at least one viewer, the FKiSS way of displaying a cel with a message means that, by positioning the message cels, you can display consecutive messages under each other, unmap the first message before mapping the next, or go from one message to the next with a "continue" button. You can even include a picture in the message, like big red exclamation mark. Why does anyone use notify() at all?

UltraKiSS adds confirm() and showstatus(). These commands don't belong in the FKiSS specifications, and only work in UltraKiSS.

To quote from the UltraKiSS documentation:

The confirm() action will display a modal message dialog on the screen. Modal confirmation dialogs require a Yes or No response. The result argument must be a variable that returns the user confirmation response to the dialog. The remaining arguments specify the text to be displayed in the window and can be variable or literal strings. Each argument is converted to its string representation and concatenated with all other arguments in the order specified.

The result variable is set to 1 if the dialog is closed with a Yes response, and 0 otherwise. Confirm() dialogs suspend dynamic execution. FKiSS events cannot proceed until the dialog is closed. For dialogs that do not require waiting for a response, use the notify() statement.

Okay, in beginner's terms: confirm() pops up a message showing either the text you put in it, or the contents of a string variable you put in it (yes, UltraKiSS uses string variables, ie. variables that can contain text) and a Yes/No button. You can put in several strings and variables, separated by commas; they will be combined into one text. When the message pops up, everything freezes until you choose Yes or No. You also have to include a variable name in confirm() that will be set by choosing Yes or No: if Yes, its value becomes 1, otherwise 0. The example given is:

confirm(A,"Variable X is: ",X)

The UltraKiSS documentation has this to say about showstatus():

The showstatus() action displays a message on the viewer status bar. The arguments specify the text to be displayed in the status line and can be variable or literal strings. Each argument is converted to its string representation and concatenated with all other arguments in the order specified.

To set the status line to its default state, use showstatus() without any arguments.

As opposed to popping up a message that cannot be ignored, showstatus writes a text, string variable or concatenation of any number of strings and string variables to the status bar underneath, where it doesn't hinder gameplay or draw attention to itself, and is easy to miss. The strings and variables are separated by commas, as with confirm():

showstatus("Variable X is: ",X)

To blank the status bar, use "showstatus("")", although I've found that the status bar is automatically cleared when closing a confirm() message or switching to a different page. In fact,

;@  showstatus("This is page 1")
does not display the message, although
;@  showstatus("This is page 1.")
;@  confirm(A,"Could you take a look at the status bar?")
will display the message "This is page 1." in the status bar until the confirm() dialog is closed, which suggests that set() doesn't clear the status bar until after all the code under it is processed. Then again, set() doesn't so much clear the status bar as fill it with an implicit showstatus() message: "Kisekae UltraKiSS V3.3b (c) 2002-2018 William Miles". To start with a blank status bar on any page requires an alarm and the following code:
;@set(1)        ; the page that needs its status bar blanked
;@  timer(5,1)  ; wait one millisecond...
;@  showstatus("") ; aaaand blank.

To see what the first two commands do in different viewers, I made a demo set with all four commands that I tested in UltraKiSS and GnomeKiSS. The way messages are handled were as different as I thought they would be.

From having tried fkiss-x decades ago, I know that in Linux, debug() writes to the terminal that the viewer is called from. As, in my desktop environment, GnomeKiSS is called from the menu, debug() does nothing. It also does nothing in any Windows viewers I remember. In UltraKiSS, which has an option to trace FKiSS for debugging, debug() opens the trace window and displays its message there.

The debug() example did show that GnomeKiSS doesn't like brackets. I got an error message that "message()" is not a command, when I used

;@  debug("This is a debug() message")
and had to change it to something like
;@  debug("This is a debug message, no brackets in this string!")

GnomeKiSS is very good with notify(), not showing the second message until the first has been closed. UltraKiSS, like PlayFKiSS, pops the messages up one after the other so the last one is on top. Neither play an Error sound.

When using showstatus(), UltraKiSS always shows the latest message, flushing out the one before it. The status bar is filled with a standard message after every page change. As confirm() freezes the set, it doesn't have the problem that notify() does, where one message is popped up on top of another.

Click here to download a demo set.

Back Previous Next