Messaging functions

This tells how script plugins can “print” messages to a user. It is a reference manual for several functions in the ScriptFu language.

Some of the functions are like in other Scheme language implementations, but have additional effects since ScriptFu is the “system” that wraps or catches their effects. Most scheme functions we discuss are called for their side effects, and not for the value they return.

Introduction

A script can show messages for debugging, or about errors. Also known as “printing” messages.

Messages from scripts can go to:

1. a GIMP Error Dialog
2. the GIMP Error Console, an optional dockable in the GIMP app
3. any terminal from which GIMP was started. A user does not always start GIMP in a terminal.
4. the ScriptFu Console, a script IDE

This document says “show” and then explains what is printed to what destination in various cases.

Messaging functions

PDB procedure gimp-message

(gimp-message <string>) => ()

Shows a message as a “Warning” to the user of the script.

The function returns NIL to the script. A script calls it for its side effects.

The only argument is a string.

This is a procedure in the PDB (the GIMP Procedural Database.) It is not a function in most Schemes. Since it is in the PDB, plugins in other languages can call it.

Destination:

1. When the GIMP app has a GUI and the user has opened the GIMP Error Console : shows in the GIMP Error Console. GIMP brings the GIMP Error Console to the top and flashes it so the user should not miss the message. GIMP labels the message with “Warning”.

2. When the GIMP app has a GUI and the user has NOT opened the GIMP Error Console: shows in the GIMP status bar. This may flash by quickly, and the user can miss seeing it.

3. When the GIMP app has no GUI i.e. in batch mode: shows as text in the terminal where GIMP batch mode was started.

The display function

(display <any> ... ) => ()

Shows the usual Scheme representation of its arguments. That is, shows lists in parenthesis, functions by #\<CLOSURE>, etc.

This is a side effect, and the function returns nil.

Variadic. Takes one or more arguments.

Destination:

1. When GIMP was started from a terminal: shows to the terminal i.e. stdout.

2. When GIMP was NOT started from a terminal: shows nowhere.

3. When called from the ScriptFu Console: shows in the history pane, but only after the entire script is evaluated. That is, IO is not flushed after every call to display.

Formerly, in ScriptFu v2, behavior was different. See: Using the display function to write to the terminal

The print function

Same as display, but appends a line separator character. (Probably for backward compatibility with scripts written in the SIOD dialect back then.)

Equivalent to:

(display foo)
(newline)

Not part of R5RS. Sometime known as displayln.

The error function

(error <reason string> ...) => nothing, does not yield or continue

Stops script execution and shows a string representation of its arguments to GIMP as an error message.

Does not return so yields nothing.

Variadic, arguments can be any Scheme object:

• When the first argument is a string, ScriptFu does not show its representation surrounded by quote characters.
• When the first argument is not a string, ScriptFu substitutes -- for the missing reason string, followed by the representation of the first argument.

This function is not in R5RS but is like in other Schemes. It behaves in ScriptFu like it does in SRFI 23.

Destination of the error message:

1. When the Gimp app has a GUI, and the user has not opened the GIMP Error Console : shown in a separate GIMP Error Dialog requiring user to acknowledge by choosing the OK button.

2. When the Gimp app has a GUI, and the user has opened the GIMP Error Console: shown in the GIMP Error Console, but, remember, a user is not required to acknowledge.

3. When the Gimp app is in batch mode (started from a terminal and without a GUI): prints to said terminal i.e. stdout.

4. When called in the ScriptFu Console: shows “Error: Reason <…>” and nothing else. Shows nothing to any terminal where Gimp was started. Shows nothing to any open GIMP Error Console.

The quit function

(quit <int>) => nothing

Just stops script execution. In the ScriptFu Console, does not close the window.

When a non-zero integer is passed, returns an error to GIMP and writes to the current output port.

The integer arg to quit is optional and seting it to 0 is usually not necessary. Only a non-zero integer returns an error to GIMP or the calling plugin.

To make a script return at failure in a informative manner, you can do this:

(define (script-fu-my-plugin)
    ...
  (gimp-message "Too many drawables.")
  (quit -1)
  (display "this never evaluated")
)
...

The any->string function

(any->string <object>) => <string>

Returns a string representation of any Scheme object.

The representation is as you would see in most REPL’s like the ScriptFu Console. Some representations are as sharp constants, having prefix the # character:

>(any->string gimp-message)
#<CLOSURE>

That is, the object gimp-message is a function.

This function is in ScriptFu since Gimp v3. This function is not in R5RS. It is similar to the repr special method of Python.

Progress messages