Messages, Reminders, Hints

MSG: "msg_text"

Displays a message box with a specified text.

User-defined variables and nnCron's predefined variables can be used in text of a message. For example, to add a quotation mark character, percent sign character or new line symbol to the text of a message, use variables %QUOTE%, %PERCENT% and %crlf% respectively. By using variable %FILE: filename%, you can display contents of a specified file in a message box.

After a message box has been displayed, execution of the task is suspended until the user clicks OK button.

Examples:

MSG: "Work is 100%PERCENT% complete"
MSG: "Hello, %USERNAME%!"
MSG: "Isn't it time to go home?"

There also exist a postfix version of this command:

S" Hello, world!" MsgBox
\ converting number on the stack ('115') to a string
\ and displaying it on screen
115 N>S MsgBox

TMSG: "msg_text" <time_in_sec>

This word works similarly to MSG, but it displays a message only for a specified time (in seconds), after which it closes the message and resumes execution of the task. A user can close the message before this time has elapsed by clicking OK button.

Examples:

\ this message is displayed for three seconds
TMSG: "Everything's ready!" 3
\ this message is displayed for five second
TMSG: "Hello, %USERNAME%!" 5

There also exist a postfix version of this word:

S" Hello, world!" 3 TimeMsgBox

ERR-MSG: "msg_text"

Works just like MSG, but contains an error icon instead of information icon.

ERR-MSG is best used to warn a user that something has gone wrong.

QUERY: "query_text"

This word displays a query message box with a specified question. If the user answers affirmatively (clicks YES), QUERY: returns TRUE (-1).


Example:

#( test_query
\ every weekday, at 18:00 querying the user 
\ and turning off the computer if he answers YES
Time: 0 18 * * 1-5 *
Rule: QUERY: "Shutdown your PC?"
Action: 
    POWEROFF
)#

TQUERY: "query_text" <timeout_in_sec> Yes/No

Similar to QUERY:, but waits for the user's response during a specified number of seconds. If user does not respond, the value specified in the last argument will be used as the answer (Yes or No).

Example:

#( test_tquery
\ every weekday, at 18:00 querying the user 
\ and turning off the computer if the user  answers YES
\ or if he does not respond within 30 seconds
Time: 0 18 * * 1-5 *
Rule: TQUERY: "Shutdown your PC?" 30 Yes
Action: 
    POWEROFF
)#

REMINDER: "reminder_text"

Displays a message accompanied by a sound signal and provides an option to repeat it after a certain number of minutes.

Sometimes reminders may have been missed because nnCron was not running. Select 'Display missed reminder' checkbox if you want nnCron to run missed reminder 'at the first opportunity' - at the top of the first minute after nnCron startup (see this chapter for details).

HINT: "hint_text"

Displays a small hint message and proceeds with execution of the task, regardless of user's reaction.

You can move a hint to any place on the screen by simply dragging it with your mouse.

A hint can be closed either manually (by right-clicking on it and selecting Close from context menu) or programmatically from the task, by using word HINT-OFF.

See also Hint Options.

HINT-OFF

Closes a hint message

HINTW: "hint_text"

Similar to HINT, but suspends execution of the task until the user closes hint message manually or until it is closed with HINT-OFF.

See also Hint Options.

THINT: "hint_text" <time_in_sec>

Displays a hint during a specified period of time (in seconds). A user can close the hint earlier by clicking on it. Task execution is not suspended.

See also Hint Options.

THINTW: "hint_text" <time_in_sec>

Displays a hint during a specified period of time (in seconds), suspending execution of the task. After the time expires, the hint automatically closes and execution of task is resumed. The user can close the hint at any time by clicking on it.

See also Hint Options.

Hint Options

You can use the following options before words HINT:, HINTW:, THINT: and THINTW: to control size and position of hint box:

HINT-POS: x y
(There also exist a postfix version of this command: x y HINT-POS) 		specify position of hint box
HINT-SIZE: w h
(There also exist a postfix version of this command: w h HINT-SIZE)		 specify dimensions of hint box

The following postfix options let you specify the color of hint background and foreground, the font face and font size:

<bgcolor> <fgcolor> HINT-COLOR

specify the color of hint background and foreground. The color should be specified as hex-digit:

0x000000 - black
0xFFFFFF - white
0xFF0000 - red
0x00FF00 - green
0x0000FF - blue
0xFFFF00 - yellow etc...

S" font name" <font-size> HINT-FONT specify the font face and font size

Example:

HINT-POS: 200 200 HINT-SIZE: 200 200
0x00FF3333 0x00000000 HINT-COLOR
S" Times New Roman" 26 HINT-FONT
THINT: "This is a hint" 5

BALLOON: "balloon_title" "balloon_text"

Displays a small hint message with a specified title and text and proceeds with execution of the task regardless of the user reaction. The balloon hint appears near nnCron icon in system tray.

A hint can be closed by clicking on it or on Close button in the upper right corner. If a hint is not closed manually, it will disappear by itself after some time. Note: hint will not disappear automatically if currently there is no user activity - mouse clicks, keyboard key presses.

Example:

#( test_backup
NoActive
Action:
    BALLOON: "Attention!" "Task %QUOTE%%CUR-TASK-NAME%%QUOTE% has been started"
    BEEP: 250 500
)#

You can close the hint by calling BALLOON: with empty title and text:

#( test_backup1
NoActive
Action:
    \ displaying the balloon
    BALLOON: "????????!" "?????????? ?????? %QUOTE%%CUR-TASK-NAME%%QUOTE%"
    BEEP: 250 500
    PAUSE: 2000
    \ closing the balloon
    BALLOON: "" ""
)#

You can customize BALLOON: behaviour using the following variables:

BalloonTime

Sets the time (in ms), after which balloon hint will be closed by the system. The system enforces minimum and maximum timeout values (10000 ms and 30000 ms, respectively). Values that are too large are set to the maximum value and values that are too small default to the minimum value. Thus, you can control the time in the range from 10000 ms to 30000 ms. Default value - 10000 ms.
BalloonIcon

Sets the icon, that will be displayed in balloon hint:

  • 0 - no icon
  • 1 - Asterisk icon ()
  • 2 - Warning icon ()
  • 3 - Error icon ()

Default value - 1.

Example:

#( test_backup2
NoActive
Action:
    \ in the case of error
    30000 BalloonTime !
    3 BalloonIcon !
    BALLOON: "Error!" "Error in task %QUOTE%%CUR-TASK-NAME%%QUOTE%"
    BEEP: 250 500
)#

There also exist a postfix version of this command:

S" title" S" text" BALLOON

The word BALLOON: can be used only in Win2000/XP.

Note: if BALLOON: seems not to work on your PC check the following registry path: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced. The value EnableBalloonTips need to be set to dword:00000001.

See also: TrayIconBalloonClick:, OnBalloonClick.

WIN-INPUT-TEXT: "caption_text" "prompt_text" "default_input_text" <time_in_sec>

Displays a dialog window with a propmpt to enter something in an input field. The information you have entered can be used somewhere in the task as a string.

There are 4 arguments to the word WIN-INPUT-TEXT: 3 strings with dialog window caption text, the prompt text and the default text which is displayed in an input field. The fourth argument is a time (in seconds). During the specified time the dialog window will be displayed on a screen, waiting for the user's input. If there is no user's input during the specified time the dialog window will be automatically closed. You can enter 0 as the fourth argument to display the dialog window permanently, without any time out.

Here is what the word WIN-INPUT-TEXT: returns:

Examples:

#( test_win_input_text
\ an example with placing the string on a stack
NoActive
Action:
WIN-INPUT-TEXT: "Just a test" "Please, enter your first name" "Type here" 0 0=
IF
    MSG: "Hi, %1 esPICKS%!"
ELSE
    MSG: "The user has no name..."
THEN
)#

#( test_win_input_text1
\ an example with placing a string to an array
CREATE input_geography 256 ALLOT
NoActive
Action:
WIN-INPUT-TEXT: "Another test" "Where are you from?" "Type here" 0 0=
IF
    input_geography PLACE
    MSG: "You are from %input_geography COUNT%!"
ELSE
    MSG: "This user is from nowhere..."
THEN
)#

#( test_win_input_text2
\ an example of converting string to numbers
CREATE input_years 256 ALLOT
NoActive
Action:
WIN-INPUT-TEXT: "The last test" "How old are you?" "Enter two digits only!" 0 0=
IF
    2DUP
    input_years PLACE
    \ converting string to a number
    \ and checking if you are older than 18:
    S>NUM 18 < 0=
    IF
        MSG: "You are >= 18 (%input_years COUNT% years old actually)!"
    ELSE
        MSG: "You are at unknown age or < 18 (%input_years COUNT%) so you can not proceed!"
    THEN
ELSE
    MSG: "This user is at unknown age..."
THEN
)#

#( test_win_input_text3
\ an example of error processing
NoActive
Action:
WIN-INPUT-TEXT: "Error processing test" "You have 30 seconds to enter something useful" "Type here" 30 DUP 0=
IF
    DROP
    MSG: "You have entered: %QUOTE%%1 esPICKS%%QUOTE%"
ELSE
    1 =
    IF
        MSG: "The user pressed CANCEL or hit the ESC key..."
    ELSE
        MSG: "The user was unable to enter smth useful in 30 seconds"
    THEN
THEN
)#

There also exist a postfix version of this command: WIN-INPUT-TEXT ( a u a u a u n -- a u 0 | -- 1/2)

S" caption_text" S" prompt_text" S" default_input_text" 0 WIN-INPUT-TEXT

See also: