Randy, all your comment are very much appreciated!
comments below
On 18 Jun 2001 09:20:49 -0400, Randy Kramer wrote:
>
> Joaquin,
>
> Joaqu�n Cuenca Abela wrote:
> > Can somebody that doesn't has a clue about how the perl bindings works
> > take a look and say me if everything is understandable?
>
> Hey, a job I'm qualified for (I think)!
>
> Very nice, and helpful to me -- one of the things I've been trying to do
> is learn Perl, at least a little bit -- reading your document has and
> will help.
>
> I do have some comments:
>
> 1. Near the beginning, please clarify: do the Perl bindings work only in
> unix, or they work in several OS's, but these *instructions* are only
> for unix, or they work in several OS's but the *installation
> instructions* are only for unix?
done
>
> 2. In the installation instructions, in or before step 2:
> -Must I first download and install some package (or does it come with
> AbiWord)? Must it be unzipped? Into a specific directory?
> -Must I be in a specific directory when I type those commands? (And
> I'm just thinking about an incident reported on one of the Mandrake
> groups -- must we tell people to type them at the command line (so they
> don't type them into AbiWord)? ;-)
lol lol lol
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)
> 3. I won't mention typos or whatever on the assumption that rms will
> look at them. If he does not have time, I can attempt to deal with them
> -- the easiest for me would be fixing them in the document and sending
> it to you -- you can spot them with diff. (I'm doing this on my Windows
> box, diff is not at hand.)
>
> 4. In "The leading "1;" is important" it should be "trailing".
>
> 4. In the $view->saveAs(filename, left, cpy) method, what does the
> "left" parameter indicate, and what are other possible values?
good catch. left was a typo, it should be ieft
>
> 5. In $view->editHeader and the next two items, is "edition point" any
> different than "insertion point"? Would "insertion point" be the
> preferred term (because it is more common)?
yes, it's the same thing. Changed to insertion point.
> Also, this document gave me my first flavor of what the Perl bindings
> look like. Very nice, I appreciate all the work you've put into this!
>
> I assume that additional bindings can be added. The first one that
> comes to mind would be "find" so that we could insert text after a
> specific word or phrase. And maybe a way to "create" a selection (find
> something, select the word/line/sentence/paragraph/section containing
> what we found, so that, perhaps, we can apply a new (character or
> paragraph) style. Maybe a way to get the character (word, whatever) at
> the current insertion point? (No hurry from my point of view -- this is
> just brainstorming -- I'm not sure when I'd attempt to make use of this
> stuff -- but I have used VBA "macros" in Word.)
very good ideas, I will add them asap
> 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
Cheers,
--
Joaqu�n Cuenca Abela
[EMAIL PROTECTED]
HOWTO USE THE ABIWORD SCRIPT BINDINGS
=====================================
How to install the beast
------------------------
1) By now, you should be in unix. The perl bindings only works 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 as:
-fno-strict-aliasing -I/usr/lib/perl5/5.6.0/i386-linux/CORE
If you see something as "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 (in 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 out 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 see now 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 ([EMAIL PROTECTED]) 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", then you're right).
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 just used 3 functions of the abiword's perl bindings, but
with only these function 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 serie of cards, 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
in 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 things than just write something in a view! You
can do weird things, 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 availables 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!
