1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
4
<title>Kaptain - A Dialog Creator</title>
6
<body bgcolor="#FFFFFF" text="#000000" link="#0000A0">
9
<center>Kaptain - A Dialog Creator</center></h1>
12
<i>"What Linux really needs ..."</i> is the beginning of an oft written statement which nearly as often ends with
13
<i>"graphical front-ends for legacy console apps." </i> To quote a certain magazine
14
editor: <i>"Of course, what Linux needs are not just dialogs, but dialogs that
15
optionally show you the command-line options they generate, so you can get used
16
to which options do what."</i> I add that it would also be nice if the dialogs
17
were easy to write, so more people would bother to create them.
21
<h2>What Kaptain can do for you.</h2>
24
<a href="http://www.hszk.bme.hu/~tz124/kaptain/" name="Kaptain">Kaptain</a>
25
has the ability to display mixed widget types in a modern looking dialog which
26
is created from a text file. The program can take care of most of the layout and
27
widget types for you. You can even write tabbed and child dialogs. And, importantly,
28
it can echo it's output to the command line for learning purposes (or the sheer delight of experimenting :-) ).
29
It also has tooltips and WhatsThis to aid in this regard. You could even use it as part of a pipe and have it written on the fly!
33
Linux is chock-full of powerful command line goodies like <b>enscript</b> and <b>mpage</b>, but, even if
34
you were a member of their frequent-flyer program, you'd never be able to remember all the
35
switches and options included with them. <b>Kaptain</b> is perfect for this sort of thing: lots of spinners,
36
check-boxes and combos etc. Then there are those file conversion chores. I have
37
constructed many, er, <i>interesting</i> looking pipelines to convert image, sound and text formats. The
38
latter do surrender to a little bash function - as long as you don't need to change any options for any of the commands.
39
By the time you write enough shell script to handle all the options... you need to write a man page for your shell script.
42
<a href="images/enscript1.gif"><img src="images/enscript1_thumbnail.jpg" width="250" height="248" vspace="10" hspace="10" alt="A tabbed dialog for enscript" align="right"></a>
44
<p>I wouldn't be writing this if <a
45
href="http://www.hszk.bme.hu/~tz124/kaptain/" name="kaptain">Kaptain</a>
46
couldn't do all of that, but I'd be lying if I said that it looked easy to <i>me</i>
47
right away. I'd like to re-stress the "me" in the preceding sentence: I'd never
48
written in anything object oriented before. If you've done any at all, I'm
49
sure <b>Kaptain</b> will be a cake-walk for you. And, if you haven't, don't
50
fret. I'm living proof that you'll be writing scripts for <b>Kaptain</b>
51
without stressing yourself overmuch.</p>
55
If you're already handy with OOP-type languages, I suggest you just download the
56
thing and dive in - you'll love it.
60
The image is a thumbnail of the <b>enscript</b> dialog. You can click on it for a larger view.
63
Even if you have no intention of writing anything, there are many example
64
scripts in the <b>Kaptain</b> source tarball to make it worth the download:
87
Now, as alluded to earlier, I had never done any scripting which involved '->',
88
objects or inheritance at all. Sure, I'd copied and pasted Java like
89
many others have, but I didn't really <i>get</i> it. Any changes were
90
nearly pure trial and error. Anything that actually worked after I messed with it was pure accident.
94
I think I just wasn't properly pre-disposed to learning it. After all, the only
95
example of object oriented programming that I (or most other people) are
96
familiar seeing as code, is Java. We're aware of Java, because it turns our
97
normally speedy browsers into 3-toed sloths on vallium. I simply could not understand
98
what all the hype was about since I always dreaded seeing 'loading java' or
99
similar in Netscape. Apparently, <b>it doesn't have to be that way</b>. It's
100
really a wonderful way to write once you get into it. I'd known for years about
101
it being done even in perl, but I never got past my experience watching Java
102
ruin an evening's browsing. I was recently vindicated in my attitude towards
103
Java in the January 2001 issue of "Software Development". On page 26 the author
104
states: "<i>I'm primarily a Java hacker ... My Plan A for dealing with a
105
memory-hungry application ... is to wave my hand and snort 'Bah! That is why we
106
have virtual memory.' The 20-GB hard disk on this system seems positively
107
claustrophobic to me.</i>" I knew it! To be fair, this was in the introduction to an article on
108
embedded, so I hope it was meant as humour. I hope. </p>
112
<h2>Let's create a dialog.</h2>
115
I can't think of any reason not to use my own first dialog as a starting point,
116
so we're going to make a simple dialog to hear phone messages from
122
<h3>What we need to do.</h3>
125
Well, we want to display and play voice messages from a graphical user interface.
126
The messages live in a directory named /var/spool/voice/incoming. We want to
127
display the messages in a list, pick one and play it. Sounds simple - and
128
<b>Kaptain</b> keeps it that way. </p>
135
I'm going to describe making a script executable here, because I dimly recall being
136
mystified when I first started with Linux by what I took to be weird "comments" on the top of some
137
scripts and I hope it may help others. Just skip down to <A href="#goodstuff">The good stuff</A> in order to avoid it.
141
First, lets make a file called 'playmessage'. So, we open a shell and type
142
"touch playmessage" or open our favourite editor and 'save as'. Whichever, at
143
some point, you need to be editing a file called 'playmessage' or similar. A
144
nice place to put this sort of thing is in "/home/yourname/bin", because it's
145
likely allready a part of your path and you have permissions for it all the
146
time. If the directory doesn't exist just create it with mkdir.
150
The first line of our script will be a 'shebang' line. Any file under linux is
151
'executable', i.e. a program, if it has its <i>x</i> bit set. Even if it's not
152
really a program, but only a script, the first line can tell the operating
153
system how to handle it as if it were a real program. The upshot is that you can
154
type the filename and it will be executed.
158
Next we need to know just where <b>kaptain</b> was installed. Pop up an xterm
159
or drop into console and type "which kaptain" and then enter.
160
Mine happens to say "/home/paul/bin/kaptain", but yours is more likely to say
161
"/usr/bin/kaptain" or "/usr/local/bin/kaptain". Now that we know where kaptain
162
is installed, we can write our first line:<br>
170
We're ready to write our script. The last thing we need to do, before we launch
171
right in, is to set the 'executable' bit on our new "program". Go back into your
172
shell and make sure you're in the directory which contains 'playmessage'. Now
173
type "chmod +x playmessage". This will set all the executable bits to on. Now a directory listing with 'ls'
174
should show 'playmessage' in green with an asterisk beside it indicating
175
that it's executable.
180
<h3><A name="goodstuff">The good stuff.</A></h3>
183
There are only ten lines in this dialog and two of them are just for show. The only things they do
184
are to show a title and an icon. Really, we could do without the "Dismiss" button as well. I want to impress
185
on you just how few lines you need in order to get a functional dialog. A 'copy and paste' plain text version
186
is <A HREF="./text/playmessage" NAME="link to plaintext">here.</A>
189
<img src="images/playmessage.gif" width="543" height="282" vspace="10" hspace="10" alt="snapshot of the playmessage dialog">
191
<p>Here's our first line:</p>
192
<pre>start "Play Message" -> descr msglist;</pre>
195
Note the semi-colon at the end of the line. This is mandatory, just like perl. In fact Kaptain is quite "perlish"
196
after a fashion. The main container is actually named 'start', this is also built into Kaptain's grammar and you must
197
use this word for your first rule. The quoted string "Play Message" is optional and is used only for the dialog's window title.
201
On the right, that is, after the "->", you can see the words "descr" and "msglist". In Kaptain grammar these are known as 'nonterminals' and
202
they refer to some area of the dialog. They may be named anything you like as long as they start with a letter. You can also specify as
203
many areas as you like.
207
So far, we've defined a dialog with two areas named "descr" and "msglist". If you try to run this without adding anything more it will fail. Why? Because,
208
the areas named don't resolve to anything - we haven't defined them yet. These next three lines define the "descr" area of the dialog:
212
descr :horizontal -> title pic;
213
title -> @text ("Phone Message player.");
214
pic -> @icon("/usr/share/icons/large/kvoice.xpm");
218
The first line of "descr" is just about the same as the very first line of our script and it does pretty much the same thing. It defines two
219
areas of the dialog. The only difference is the ':horizontal' option. This forces Kaptain to lay them out side by side instead of vertically. Of
220
course now these <i>new</i> areas need to be terminated (or point to yet more areas) and they do in the next two lines following them.
221
"title" now points to a text widget and "pic" points to an icon. Kaptain grammar calls these <i>"specials"</i>. There's a list of all the currently
222
available specials <a href="specials.html">here.</a> These include spinners, combos, file dialogs etc.
226
These last lines complete the whole dialog by terminating the "msglist" area of the dialog:
230
msglist :framed :horizontal -> msg buttons;
231
msg -> @list(`ls /var/spool/voice/incoming`);
233
buttons -> play close;
234
play -> @action(play_rmd)="Play";
235
close -> @close="Dismiss";
237
play_rmd -> "rmdtopvf /var/spool/voice/incoming/"msg" | pvftowav | play -t wav - ";
241
Again, we see a familiar line. "msglist" has just added two child areas to itself. Now that you know what the ":horizontal" option does, I
242
think you can guess at the ":framed" option.
246
The next line - the one for "msg" - is interesting. It's both simple and powerful. I'm sure you've figured out that "@list" is responsible for
247
the list box shown in the dialog, but look where it gets it's contents from: a line of shell script! Anything in back-quotes (n.b. It's the key to the left
248
of the "1" on your keyboard, the regular single quote won't work.) will be executed and it's standard out will be fed into the "special". You can stuff
249
anything in there, "perl -e" - whatever, even multi-line.
252
<p>The only area left now is the one for the buttons. This area spins off two more children, one for each button we want. The play button shows
253
another way to execute some shell commands, this time a pipeline for converting and playing raw modem files. That's it. Again, to see the script as
254
plain text you may click <A HREF="./text/playmessage" NAME="link to plaintext">here.</A> It's nice to see it all together now that you know how it works.
255
Simple as it is, you could tinker a bit if you like: feed the list your music directory and change the play command to your mp3 player for example. Process
256
text files, convert images; it can be the basis for a lot of things.
260
Anything this easy becomes nearly addictive and I was sorely tempted to start "embroidering" the script. Since I only have one way of dealing with
261
temptation (I yield to it) a pic of the over-grown results is <a href="images/voxpak.gif">here</a> and the script is <a href="text/voxpak">here.</a> This exercise
262
was useful for two reasons: a) I got something to replace my now kde2-broken <b>kvoice</b> and b) I learned the limitations of <b>Kaptain</b>. You can't
263
refresh lists or change anything after it's up (of course widget settings <i>do</i> change things). Commands are evaluated only at run-time. This is as it should be
264
for a dialog program and I really was pushing the envelope with my little kvoice experiment. So let's do what I originally set out to show.
267
<h3>A dialog for <b>mpage</b></h3>
269
<img src="images/mpage.gif" width="289" height="302" vspace="10" hspace="10" alt="snapshot of mpage dialog" align="right">
272
If you've seen the command line options for <b>mpage</b> you're probably afraid right now. Very afraid. But fear not. We're only going to use a small subset of mpage's options.
273
And, because we've taken a good look at the basics, I'm not going to go through it line by line. I'm including this here to show off the @echo special more than anything.
278
For those who aren't familiar with <b>mpage</b>, it's a command line program for printing multiple pages on a single page. You can print 2, 4 or 8 up, but you'd better
279
have exceptional eyesight and a good printer for 8:1! The other noteworthy thing about <b>mpage</b> is that it has about 50 options you can feed it - in fact, the sheer number of
280
options is listed under 'BUGS' in the man page :-) I'm sure I'll embroider this script over time too, but for now let's just choose between how many pages and the margin controls.
288
#!/home/paul/bin/kaptain -V
290
start :framed "mpage Mini-Dialog" -> file numpages margins buttons;
292
file "File to print" -> @infile("*.txt");
294
numpages :horizontal "Number of pages on each page" -> p1 | ! p2 | p4 | p8;
300
margins :horizontal "Margins" -> left right top bottom;
301
left "Left" -> @integer(10,100)=40;
302
right "Right" -> @integer(10,100)=50;
303
top "Top" -> @integer(10,100)=20;
304
bottom "Bottom" -> @integer(10,100)=30;
306
buttons :horizontal -> echo print dismiss;
307
echo -> @echo(cmd)="Echo";
308
print -> @action(cmd)="Print";
309
dismiss -> @close()="Dismiss";
311
cmd -> "mpage -P -"numpages" -m"left"l"bottom"b"top"t"right"r "file;
315
<p>Plain text is <A HREF="./text/mpage.kaptn" NAME="link to plaintext">here.</A></p>
318
When run from an xterm, you can make changes and click the "Echo" button over and over to see how the changes effect the command line
319
without wasting any paper at all. To really save on paper just take out the "-P" and everything will go to standard out even if you press print.
320
To really enjoy playing with it change the cmd line to:
322
<pre>cmd -> "mpage -"numpages" -m"left"l"bottom"b"top"t"right"r "file">test.ps";</pre>
324
then you can just view the output page with a viewer. Or you could add ";viewername test.ps" to the end and save a step - you get the idea.
328
I haven't really scratched the surface here. There's heaps more I haven't shown or even mentioned. <b>Kaptain</b> comes with pretty good docs and
329
plenty of examples though. The author of <b>Kaptain</b> is <b>Ter�k Zsolt</b>. He's doing a great job with <b>Kaptain</b> - which is still only at 0.6. If it gains wider use it
330
can be of great value in teaching console apps and it can save all of us some mind-numbing tedium. Plus it's the most painless way to experiment with output I've ever
331
found. Don't wait for someone to write one for you - give it a shot yourself. Really. Mr. Ter�k will be pleased to post them on his <a href="http://www.hszk.bme.hu/~tz124/kaptain/">website.</a>
335
There are other dialog programs for X out there: <b>gdialog</b> which is probably on your system already, <b>Xdialog</b> which has some nice date/time dialogs etc.
336
is down-loadable from <a href="****where****">here.</a> Finally, <b>dldialog</b> is nearly a little world by itself. You can find <a href="****where">dldialog here.</a>
337
If one dialog app doesn't have exactly what you want there are always options. I'm sure there are others I just haven't tried yet. Mix and match them within the same script.
338
<!-- shameless advocacy -->
339
With Linux you're not short of tools to get the job done.
added
removed
doc/article-kaptain/index.html
