Re: Gtk::perl documentation?

On Wed, 2003-04-16 at 15:20, muppet wrote:

[see below for the answer!]

Yow! No kidding! But first

the 40k-foot overviews in the API reference and tutorials are good, because
they introduce the basic concepts for the hard stuff, like TreeView and
TextBuffer and other such things.

In my mind, the API ref overviews are ground troop implementor level...
as a user of library functions I specifically do *NOT* want to know how
they work, not that it's not interesting... 

Now Stephen Wilhelm's toot
is great because it describes Gtk in terms of *what it does*; 'buttons
and boxes relate like so'. (The examples are a big help obviously). He
shows what widgets have in common, etc; it's specifically *not* an
alphabetical listing of function calls, which is all the ref provides.
Once I have an idea what a bunch of functions *do*, then I can rummage
around in the ref for specifics and trivia.

At this point I'm either just grousing, or wishing :-) Mostly wishing, I
hope, since there's not a Big Document that I'm missing. Alas, I'm not
an interface sorta person (system & hardware work mostly) so I'll never
be able to devote the time necessary to extend the tutorial.

....  there are too many GTK functions to
document in perl, especially if the docs would be 95% copied.   it's wasteful
and error-prone.   i think we'd be best off providing a document which
describes the general principles behind how the bindings map C to perl, and
detail specific places where the perl API is different from the C one.

Agreed, certainly, as it applies to library interface.

here's a brain-dump that might serve as the beginnings of that document for
new-gtk2-perl, which is modelled after gtk-perl:

No kidding! So I take it new-gtk2-perl is more orthogonal than gtk is
now? Are there that many inconsistencies?

  thus, b = gtk_button_new_with_mnemonic (str); becomes
  $b = Gtk2::Button->new_with_mnemonic ($str);

Aargh, I guess this should have been obvious, in that a button with a
mnemonic label & a keyboard shortcut is likely a superset of Button, so
it just needs a funny constructor, but once constructed, it's a Button.

Now that I know the answer it's 'obvious' but the line of reasoning
isn't so automatic... (this is turned to design philosophy and highly
subjective, YMMV) I could argue that the above is more inconsistent than
a new class Button_with_mnemonic with a simple constructor 'new' since
we already have many classes (the various button types) all based upon a
more basic class. It's coin-toss time.

I'll have to take a look at what you're doing with new-gtk2-perl, if
only that you're cleaning up the name space! :-) I'd be perfectly happy
if (1) you shotgunned it all down to a vastly reduced number of base
classes (buttons, for instance) and a zillion special
constructor/methods that create all the variants and (2) it became very
popular so I wouldn't have to swim upstream :-( alas, when I write
system tools they gotta run on base install machines, no extra CPAN or
installing modules, an unfortunate but required constraint for me.

 you can catch a
croak very easily by wrapping the function in an eval:

   eval { $pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename); };
   if ($@) {
        # couldn't open the file, $@ has the message
   } else {
        # do something with $pixbuf

(I wish more people would actually anticipate errors; one python package
I run to glue my email together on my laptop tracebacks when I invoked
it with "--version"! Sheesh! My rule of thumb is: programming is all
error handling. Just look at TCP/IP...)

there.  just about everything you need to know.  what else?  =)

Umm, can you write my program for me? That would be a big help... 

Seriously, thanks a million for the interface overview. I've actually
saved it and will refer to it. I know it's for new-gtk2, but it appears
to reveal the (better parts of) gtk-perl...

I guess the short answer to my question is, no, there is no other
documentation. However, I will review or at least write up how useful I
find the Linux GTK book when I get it.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]