Script-fu Dialog box

From OSP Wiki

Contents 1 Overview 2 Example script 3 Argument types 4 Arguments and options explained 4.1 SF-IMAGE 4.1.1 Data type returned 4.1.2 Options 4.1.3 Uses 4.2 SF-DRAWABLE 4.2.1 Data type returned 4.2.2 Options 4.2.3 Uses 4.3 SF-ADJUSTMENT 4.3.1 Data type returned 4.3.2 Options 4.3.3 Uses 4.4 SF-COLOR 4.4.1 Data type returned 4.4.2 Options 4.4.3 Uses 4.5 SF-TOGGLE 4.5.1 Data type returned 4.5.2 Options 4.5.3 Uses 4.6 SF-STRING 4.6.1 Data type returned 4.6.2 Options 4.6.3 Uses 4.7 SF-VALUE 4.7.1 Data type returned 4.7.2 Options 4.7.3 Uses 4.8 SF-FONT 4.8.1 Data type returned 4.8.2 Options 4.8.3 Uses 4.9 SF-GRADIENT 4.9.1 Data type returned 4.9.2 Options 4.9.3 Uses 4.10 SF-OPTION 4.10.1 Data type returned 4.10.2 Options 4.10.3 Uses 4.11 SF-PATTERN 4.11.1 Data type returned 4.11.2 Options 4.11.3 Uses 4.12 SF-FILENAME 4.12.1 Data type returned 4.12.2 Options 4.12.3 Uses

This tutorial was last tested for the Gimp 2.2.13 (and is the same for Gimp 2.3)

Overview

When you create a Script-Fu script you can have it pop up a dialog box and ask the user for input. I will explain what I have worked out about the different arguments used.

Example script

(script-fu-register "dummy-script"
		"<Toolbox>/Xtns/My Stuff/Demo Box..."
		"Do nothing"
		"Your Name"
		"Your Name"
		"August 2007"
		"*"
		SF-IMAGE	"Image"			0
		SF-DRAWABLE	"Drawable"		0
		SF-ADJUSTMENT	"Slider"		'( 30 1 2000 1 10 1 0)
		SF-ADJUSTMENT	"Input box"		'(400 1 2000 1 10 1 1)
		SF-COLOR	"Colour picker"		'(255 0 0)
		SF-TOGGLE	"True/False tick box"	TRUE
		SF-STRING	"Text String"		"Whatever you want goes here"
		SF-VALUE	"Number value"		"0"
		SF-FONT		"Font"			"Arial"
		SF-GRADIENT	"Gradient"		"Default"
		SF-OPTION	"Multi Option"		'("Option 1" "Option 2" "Option 3")
		SF-PATTERN	"Pattern"		"Dried mud"
		SF-FILENAME	"Filename"		"~"
)

The first seven lines are explained in the main Script-fu tutorial. The rest of them produce a dialog box that looks like this:

Argument types

The following table explains each argument type

Argument	Data returned	What it is used for
SF-IMAGE	The ID of the current image	Only really used in scripts that alter an image that is open.
SF-DRAWABLE	The ID of the current layer	Ditto.
SF-ADJUSTMENT	A single number between the min and max that you set in your script	It can be in a slider bar format or an input box.
SF-COLOR	A list of three numbers, each between 0 and 255	When you want to allow the user to select their own colour.
SF-TOGGLE	TRUE or FALSE value	Lets the user turn a feature on or off.
SF-STRING	A text string	Allows the user to put in any text they desire.
SF-VALUE	A number	When you want to allow the user can put in any number they desire, there is no minimum or maximum.
SF-FONT	A font name	Allows the user to specify what font they want to use.
SF-GRADIENT	A gradient	Allows the user to choose from a gradient available to them in GIMP.
SF-OPTION	A text string	You can limit the user to a list of predetermined text options.
SF-PATTERN	A pattern	Allows the user to choose from a pattern available to them in GIMP.
SF-FILENAME	A file name	Allows the user to use the file picker to specify a file that already exists.

Arguments and options explained

The first option of the argument is the text that is displayed in the dialog box for the user. Except the first two arguments in the list, they are not displayed in the dialog box.

SF-IMAGE

Data type returned

The images ID.

Options

I have only seen it in one format "Image" 0 and have no idea what else you can call it and what would happen if you used a 1 at the end instead of a 0.

Uses

This is only really used when you are altering an image that exists already. GIMP can have several images open at once, you use this line to tell Script-Fu which image to run the action on.

One possibility is that you can create a copy of the current image and do all the operations on that image. The first action would be to copy the current image and in all of the other actions you specify the ID of the new image. Something along the lines of:

(define (example-script	theImage)

	(let* (
		(newImage (action to copy theImage))
	)

	(function newImage param1 param2)
	(function.....
.....
(script-fu-register "example-script"
		"<Toolbox>/Xtns/My Stuff/Example..."
		"Do nothing"
		"Your Name"
		"Your Name"
		"August 2007"
		"*"
SF-IMAGE	"Image"	0
.....

SF-DRAWABLE

Data type returned

The layers ID.

Options

Like the previous argument I have only seen it in one format "Drawable" 0.

Uses

This is only really used on an existing image and used to ID the layer that is currently selected. You can't alter the contents of the image using "Image". Think of the image like a painting, the "image" is the just containing frame, the drawable is a canvas and they can be stacked on top of each other.

When you want to change the size of the "image" you are doing so on the frame, the canvas (or layer) does not change size. If you want to change the colour you have to apply paint to the canvas, you can't do it to the invisible frame. Changing contrast, levels, channels mixes etc etc cannot be applied to the "image", its just a container, it has to be done to the pixels in a layer.

SF-ADJUSTMENT

Data type returned

A single number.

Options

A list of numbers, in order they are:

1. Starting value, you specify this default.
2. Min value, the user cannot go lower than this.
3. Max value, as above but the upper limit.
4. Small step, when the user single clicks it will go up or down by this value
5. Large step, when the user holds down the mouse it will step by this much
6. Integer or float, specifies if the number has to be a whole number or the user can input factions. 0 is integer, 1 is float
7. Slider or Roll box, as you can see from the example at the top both the slider and input box used this argument, 0 is the slider, 1 is the input box.

Uses

Allows a certain degree of flexibility for the user to input a number but allows you to know that the value of the number will be within a specified range.

SF-COLOR

Data type returned

A list of three numbers that specify a colour.

Options

You specify the default colour but it allows the user to pick any colour within the rainbow. You can find out a colours three number combination but using the colour picker and looking at the bottom three numbers for each channel.

The higher the number the brighter that channel, so (0 0 0) is black, (255 0 0) is pure Red and (255 255 255) is white.

Uses

This is pretty obvious, you allow the user to choose a colour, any colour and then use that colour in the image manipulations.

SF-TOGGLE

Data type returned

A TRUE or FALSE.

Options

You can specify the default.

Uses

Normally allows the user to turn a feature or option on or off (e.g. "Flatten image"). In the script you would use an if statement to detect if the user wanted the action taken. If statements are in the format:

(if (cond) (action if true) (action if false))

The condition check can be a comparison check or a Boolean check:

(if (> width height) (message "It's wider") (message "It's higher"))
(if (= flattenImage TRUE) (flatenimage function) ())

If you are doing several actions based on the check, use the begin function, an example:

(if (= highlightEdges TRUE)
 	(begin
		(action1....)
		(action2....)
		....
	)
	(action if false)
)

SF-STRING

Data type returned

A string.

Options

The default text string is placed in quotation marks.

Uses

It allows the user to input a text string, you can then use that string to name a layer, put text in the image, display a message on the screen. There are many and varied uses you can put this to.

What you cannot do is perform calculations on this input, even if the user did input a number. To the script ‘54’ is just the text character 5 followed by the text character 4 and it cannot add (or any other maths) to text.

SF-VALUE

Data type returned

A single number.

Options

You can specify the default value but the user is free to put in ANY number they want.

Uses

Be careful when using this argument, you just never know what the user thinks will be a reasonable number…. a gausian blur of 1,000,000….hmm, why not?

You and I know that it will take the computer three years to finish that but the user will think your crummy script has locked up their PC.

SF-FONT

Data type returned

A font name.

Options

You can specify the default font to use but you don’t have to. I wouldn’t unless you know it’s the exact name of a font that exists on Linux and Windows.

Uses

Combined with the SF-STRING and one of the number inputs you can allow the user finer control over the text that is added to their image.

SF-GRADIENT

Data type returned

A gradient name.

Options

You can specify the gradient to use but you can just leave it blank.

Uses

No idea, I have never used gradients in my images. If you what they do and how to use know feel free to update this section.

SF-OPTION

Data type returned

A string, limited to a predetermined list.

Options

A list of the strings you want the user to choose from, each string is within quotation marks. The selected string is then passed to the script.

Uses

When you want an input string but also want to limit the users choice… I guess…. No idea why you would want to do that but it’s there.

SF-PATTERN

Data type returned

A pattern name.

Options

You can specify the default pattern but the user can choose any other pattern from the list.

Uses

Never used it so I don’t know.

SF-FILENAME

Data type returned

A filename.

Options

You can specify the default directory location to look in but since GIMP is cross-platform and each OS uses a different format for the directories it is probably best to leave this blank.

Uses

I have not used this as yet.