Subject: Re: HOWTO use the perl bindings
From: Randy Kramer (rhkramer@fast.net)
Date: Tue Jun 19 2001 - 12:07:14 CDT
Joaquín,
Joaquín Cuenca Abela wrote:
> Randy, all your comment are very much appreciated!
You're welcome!
I've taken the liberty of revising your document (attached) to deal with
some typos and such, and conversion of some phrases to more common
american idiomatic expressions. (There will be many opinions about such
things, feel free to ignore the changes if you wish.)
Your revised document answers all my original questions (and more) -- I
would have to read it with a clear mind in a few days to see if there is
anything else.
There is one thing though: the explanation of ieft is helpful, and so is
the explanation of cpy, except it is confusing:
I can imagine we might wish to do any of the following things.
1. Export a document in a different format, but continue working with
the document in the existing format.
In this case, I think we would:
-Leave the document marked dirty
-Create a new copy on disk with the new format
2. Create a document in a different format and start working on it. In
doing this it would seem necessary to close the current document and
appropriate to save it (first) (so no changes are lost).
In this case, I think we would:
-Create a new copy on disk with the new format
-Save the copy with the current format (erase the dirty flag)
-Open the copy with the new format (not marked dirty) in the same
instance of AbiWord
3. Create a new document in a different format and open it in a new
instance of AbiWord
In this case, I think we would:
-Create a new copy on disk with the new format
-Leave the document marked dirty in the current instance of AbiWord
-Open the copy with the new format (marked ??) in a new instance of
AbiWord
4. Other?
Maybe your intent for cpy = true is closer to the third? Anyway, you
can tell I got confused. Maybe a parameter name other than cpy is a
better choice (I've assumed cpy means copy). Or a three valued
parameter:
export, copy, clone ?? (Although I'm not sure all three of the
scenarios I described are really useful.)
(I don't really know -- I'm just brainstorming here -- maybe it requires
a few days of "sleeping on it")
Reading a little more carefully, maybe your cpy = true is the second or
third scenario (not sure which), and cpy = false is the first scenario?
PS: I just realized that you must have the AbiWord source (or at least
the Perl bindings part), even if you've installed from an AbiWord
binary. Or maybe the perl bindings haven't been in any of the official
distributions so far and your instructions are intended only for
"developers" working from CVS? Depending on the answer, some more
revisions may be appropriate.
> can you please take a look at the new HOWTO (is attached with this
> email), and see if it explains all these things? (I don't want to
> explain how to install perl... I don't think that somebody should be
> able to write a perl script it he doesn't know how to install perl in
> his system)
For now I agree. If the Perl bindings become the "embedded language", I
might change my opinion.
> very good ideas, I will add them asap
Thanks! Like I said, no hurry from my point of view.
>
> > Is there / will there be a way to bind perl scripts to shortcut keys?
>
> will there be. I've managed to bind a perl script to a menubar item
> (the code is not yet finished), when that will be finished, you will be
> able to bind a shortcut key to this menubar item, and thus to bind a
> shortcut key to a perl script
Wonderful!
regards,
Randy Kramer
HOWTO USE THE ABIWORD SCRIPT BINDINGS
=====================================
How to install the beast
------------------------
1) By now, you should be in unix. The perl bindings work only in unix.
2) You should have (*surprise*) perl installed. There are many many
packages that require perl, and so most likely you will have it
already installed in your computer.
If you want to check if you already have it installed, just type:
perl -MExtUtils::Embed -e ccopts
You should see something like:
-fno-strict-aliasing -I/usr/lib/perl5/5.6.0/i386-linux/CORE
If you see something like "command not found", then you don't have
perl installed (shame on you!).
3) Go to the directory in which you have your AbiWord sources, and
type (on the command line!):
make ABI_OPT_PERL=1 install
cd src/bindings/perl
perl Makefile.PL
make
make install
3 alt.) If you are using the auto{conf,make} stuff, just write
./configure --enable-scripting
make
make install
Introductory stuff
------------------
Now, we're going to write our first script. I'm tired of "Hello
World!", so we will just write a nice "X" into the current AbiWord document.
Write the perl script:
my $frame = abi::XAP_Frame::getLastFocussed;
my $view = $frame->getCurrentView;
$view->write("X");
1;
Save it as "test_x.pl", execute abiword, and click on the
Tools->Script menubar item (or in the blue arrow in the "extra"
toolbar). Doing that will open a dialog box, select test_x.pl (and
click "ok" ;)
You should now see a sexy X in your current cursor position.
If you don't see it, take a break, make sure that you're using the
perl script enabled version of abiword, and if everything seems ok,
but it's still not working send me (e98cuenc@yahoo.com) an email with
a description of your problem.
Now, how does this script write an X in your document?
Let's analyse it.
The first line:
my $frame = abi::XAP_Frame::getLastFocussed;
creates a new local ("my") variable ($frame), and gives it the value
of the last focussed frame that AbiWord knows about (ie, the frame in
which you're working right now).
Now you should get a "view" from this "frame" to be able to write
something (if you find it awkward to "write" something in a "view"
instead of writting in a "controller", I agree).
The second line does just that:
my $view = $frame->getCurrentView;
It gets the view associated with the frame that you're using, and
stores it in the local variable "$view".
Now, we will write something in our new view:
$view->write("X");
No comments.
The trailing "1;" is important. It's the return value of your script.
If you forget about it, you will burn in hell, etc.
Here we've used only 3 of abiword's perl binding functions, but
with only these functions we can already do plenty of cool things, for
instance...
Interesting stuff
-----------------
Now, we can pass to the interesting stuff (well, I'm not saying that
inserting a X in your document is not interesting, but...)
Let's study a script that will write in the current abiword
document a series of cards (records), with the following format:
POBOX
NAME
STREET
POSTAL_CODE CITY (REGION)
COUNTRY
The data that will be used to fill each card will be extracted from
the default GnomeCard file.
Here is the script:
==============================
my $CARD;
my $home = $ENV{'HOME'} || $ENV{'LOGDIR'} || (getpwuid($<))[7] || die "You're homeless!\n";
open CARD, "< $home/.gnome/GnomeCard.gcrd" or die "Sorry, could not open default card file: $!";
while (<CARD>) {
read_card($CARD) if (/^BEGIN:VCARD/);
}
1;
sub read_card {
my $CARD = shift;
my ($name, $pobox, $extended, $street, $city, $region, $postalcode, $country);
while (<CARD>) {
if (/^END:VCARD/) {
chomp($name);
chomp($country);
my $frame = abi::XAP_Frame::getLastFocussed;
my $view = $frame->getCurrentView;
$view->write("$pobox\n") unless ($pobox eq "");
$view->write("$name\n");
$view->write("$street\n");
$view->write("$postalcode $city ($region)\n");
$view->write("$country\n");
return 0;
}
else {
my ($type, $data) = split /:/;
$name = $data if ($type eq "FN");
if ($type =~ /^ADR/) {
($pobox, $extended, $street, $city, $region, $postalcode, $country) = split(/;/, $data);
}
}
}
}
==============================
ok, now that's a lot of code... but the abi stuff is the same that we used
in the last example. We get the current frame, the associated view,
and then we write something. The key is in the "something". After that we parse
the file generated by GnomeCard (just open GnomeCard, and fill some
cards), and we write the contents of GnomeCard (formatting them a bit
on the way).
To understand how it works, take a navigator, go to google and search
for "perl tutorial". This script is not rocket science, I'm sure that
you can understand it without a glitch (if it's not the case, you can
ask me whatever you want).
Now, you can do more than just write something in a view! You
can do wierd things, such as saving documents, editing headers, etc.
Here's a list of all the methods that you can use (you can always read
the abi.xs file, but I think that the whole point of this
mini-tutorial is to show how to use the abiword perl bindings
*without* having to take a look at the code):
====================
$view->moveCursorAbs(target, where)
$view->moveCursorRel(target, where)
ex.:
$view->moveCursorAbs("page", 3);
$view->moveCursorAbs("line", 6);
It will move your cursor to the page 3, line 6.
ex.:
$view->moveCursorRel("page", -2);
$view->moveCursorRel("line", 4);
It will advance your cursor 2 pages up, and 4 lines down.
====================
$view->setCharFormat(format)
ex.:
$view->setCharFormat("font-weight" => "normal",
"font-style" => "normal",
"font-family" => "Times New Roman",
"font-size" => "12pt",
"text-decoration" => "normal");
It will change the current character format (if you write
something after this call, it will show up in the selected
format).
The formats available are:
TODO
====================
$view->changeNumColumns(ncols)
ex.:
$view->changeNumColumns(3);
It will... well, you can guess it :)
====================
$view->cmdCharDelete(forward, count)
ex.:
$view->cmdCharDelete(false, 3);
It will delete backwards 3 characters
====================
$page_nb = $view->getCurrentPageNumber
It returns the current page number
====================
$view->saveAs(filename, ieft, cpy)
It saves the doc being edited in $view as "filename".
It will be saved in the format specified by ieft, using the
following table:
1 -> AbiWord
2 -> AbiWord gzipped
4 -> HTML
5 -> RTF
6 -> Text
7 -> UTF8
8 -> LaTeX
9 -> PalmDoc
10 -> RTF attic (somebody can explain me what's that?)
11 -> WML
12 -> XHTML
13 -> DocBook
16 -> Psion TextEd
17 -> Psion Word
19 -> Applix
21 -> XSL FO
The last argument, cpy, says if the save will be "seen" by the
user or if it will be "invisible".
For instance, if you save a document named "blah.abw" as
"foo.abw" and cpy is true (1), then the user will see as the
filename of the document that (s)he is editing change from
"blah.abw" to "foo.abw", and the '*' that marks the document
as dirty will disappear.
If you save the document and cpy is false (0), then the user
will not see any visible change (besides the fact that there
will be a new file in his hard disk).
====================
$view->editHeader
It changes the insertion point to the header. Next "write"'s
will write in the header, and not in the body.
====================
$view->editFooter
It changes the insertion point to the footer. Next "write"'s
will write in the footer, and not in the body.
====================
$view->editBody
It changes the insertion point to the body of the document.
Useful after an edit{Header,Footer}. ** NOTE: It doesn't work
right now.
====================
$pos = $view->getPoint
It returns the position of the insertion point.
====================
$frame->getCurrentView
It returns the view that is being used in the frame.
====================
$frame->close
It closes the frame.
====================
$frame = openFile(filename)
It opens a new frame, using the document "filename".
====================
$frame = getLastFocussed
It returns the last focused frame.
====================
exit
Quits the app
Bye bye
-------
Now that we can dynamically add menu items to abiword, it should be a
piece of cake to package some scripts with abiword, and bind them to
new menu bar item's (a la gimp).
So, if you write a script and you think that it may be of public
interest, send us a copy and we will package it with abiword (once we
enable the perl build by default).
And that's all folks!
This archive was generated by hypermail 2b25 : Tue Jun 19 2001 - 12:12:05 CDT