The format of a special is
@name(param1, param2, ...)=initvalue
where param1
, param2
, ... and initvalue
can be either nonterminals, quoted strings or integer values.
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.