The format of a special is
@name(param1, param2, ...)=initvalue
param2, ... and
initvaluecan be either nonterminals, quoted strings or integer values.
The following specials are available in the current release
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
Guess what it can be... Note that the initial value must be quoted! Ex.:
A text input field from the user; maximum length and initial value is optional:
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
The same as
@infile, just with a Save as dialog.
The same as above, just for choosing directory. No filter string is accepted, only initial value.
@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.
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.
A text input field controlled by a regular expression:
@string("^[ab]*$") only allows to type
b letters in the field.
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 is deprecated, use
:dialog modifier instead. The argument is that it doesn't express the relation between grammatical
A button to close the current dialog. Closing the main dialog means exiting
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
@action, but Kaptain quits immediately after starting the command.
Accepts a nonterminal symbol as a parameter. It consists of a listbox and two buttons,
Add is pressed, it evaluates the nonterminal and puts the text into the listbox.
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)
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.
Information for the user slightly sunken in a frame. The parameter can be multiline text. Has no effect in the generated text.
@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:
@action but closes only the current subdialog (or the application, if it's about a top level dialog).
@action but Kaptain just forks and is going on.
@echo but then quits.
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.
@string, but shows only
A button which creates a subdialog. That contains the text generated from the nonterminal given as a parameter.
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.