4.3 Specials

The format of a special is

@name(param1, param2, ...)=initvalue

The following specials are available in the current release

@integer

An integer input from the user; you can specify valid range and inintial value if you like: @integer(-2,100)=4 means an integer between -2 and 100, initially 4. Either range or initial value can be omitted.

@float

Guess what it can be... Note that the initial value must be quoted! Ex.: @float="1.13".

@string

A text input field from the user; maximum length and initial value is optional: @string(15)="Hi, there!"

@infile

Input file. A text input field and a button from the user; a File Open dialog will appear if the button is pressed. Filter string and initial value are optional @infile("*.txt")="myfile.txt"

@outfile

The same as @infile, just with a Save as dialog.

@directory

The same as above, just for choosing directory. No filter string is accepted, only initial value. @directory="/home/joe"

@list, @combo, @combow

A simple listbox or combo box with elements from which the user should choose. @combow is read-write combo box, the others are read-only elements from the user's view. The returned value is the selected string. For example @list("cat","dog","lion","tiger").

If any of the given strings is multiline (it contains newline character), it is split to form different elements in the list. Thus @list(`ls`); would execute the command ls which gives the list of files, each on a different line, and the list box will contain the name of the files in the current directory.

The initial value, if it is integer n, makes the nth element to be selected.

@regexp

A text input field controlled by a regular expression: @string("^[ab]*$") only allows to type a and b letters in the field.

@button

A pushbutton which creates a new dialog when pressed. It accepts a nonterminal symbol as a parameter, which will form the dialog. The initial value is the text on the button. Ex.:@button(newdialog)="Settings...". @button is deprecated, use :dialog modifier instead. The argument is that it doesn't express the relation between grammatical symbols correctly.

@close

A button to close the current dialog. Closing the main dialog means exiting kaptain.

@action

A button for executing a command. If only a nonterminal is given as a parameter, it is evaluated and passed to the shell for execution. If several parameters are given (either quoted strings and nonterminals), the first one is considered to be a program and the others the parameters. For example @action(start) would evaluate the start symbol and execute it through the shell (usually bash). It is equivalent to @action("bash","-c",start). Another possibility is to use @action("perl","-e",start) to execute perl. In this case the text generated by the symbol start is meant to be perl code.

During the command is executed, the push button is disabled. When child process finishes, it is enabled again. To make Kaptain dialog disappear before executing command, use @exec.

@exec

Same as @action, but Kaptain quits immediately after starting the command.

@container

Accepts a nonterminal symbol as a parameter. It consists of a listbox and two buttons, Add and Remove. When Add is pressed, it evaluates the nonterminal and puts the text into the listbox. Remove removes the selected element from the listbox. It is useful when any number of arguments of the same type can be accepted (usually file names)

@icon

Given a file name parameter, it loads the graphic and shows it in the dialog. Has no effect in the generated text. If Kaptain was compiled with kde support, it looks for the file in the kde standard icon directories. Otherwise, full paths have to be specified.

@text

Information for the user slightly sunken in a frame. The parameter can be multiline text. Has no effect in the generated text.

@echo

Similar to @action, but it just prints the text to the standard output, never executes it. Useful when Kaptain is part of a pipe.

New features in 0.5:

@execclose

Behaves like @exec or @action but closes only the current subdialog (or the application, if it's about a top level dialog).

@fork

Similar to @exec or @action but Kaptain just forks and is going on.

@dump

Just like @echo but then quits.

@execbuffer

Parameters and initial value are like those of @action. Places a button which executes the given command and catches the standard output of the execution. After that, when it comes to text generation, it evaluates to the standard output of the command which has been executed when the button was pressed the last time.

@password

Similar to @string, but shows only *'s

@preview

A button which creates a subdialog. That contains the text generated from the nonterminal given as a parameter.

@fill

Inserts stretchable space. For example pressing the button made by @preview(start), you will see the generated text according to the current settings.

This list may improve in the future.