Re: Gtk::perl documentation?

["muppet" <scott asofyet org>]

Tom Jennings said:
> 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.

anybody want to write such a tutorial?


> > 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?

it's really not that many.  it took me a while to explain them because i talk
a lot.  actually, i'm trying to make it as consistent as possible, and as like
gtk-perl as possible --- to get both "easy to learn" and "easy to port" on the
marketing feature bullet list.


> >   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.

that's the key.  however, it's more accurately that it's a button, which
optionally can have a mnemonic label with a keyboard shortcut.  every subclass
of a button has that option, not just things subclassed from the button that
has a mnemonic.

the proliferation of funny constructors is a by-product of the fact that Gtk
itself is written in C, and C doesn't allow function overloading or default
parameters.  one thing that we have been considering for the perl interface is
overloading the constructors to allow a single "new" to do what all the
various C constructors do.  this isn't fully implemented at this time because
we're relying on the C docs, and if you see a function in the C docs, you'd
expect it to be in the perl interface (unless it's part of one of the paradigm
changes of the perl vs. C interface, i.e., no memory functions, etc).


to reduce the proliferation of constructors, we could do something along the
lines of

  $b = Gtk2::Button->new ();  # empty button
  $b = Gtk2::Button->new (label => 'hi'); # string label
  $b = Gtk2::Button->new (stock => 'gtk-ok');
  $b = Gtk2::Button->new (mnemonic => '_this is cool');
            # or however you specify mnemonics, i can't recall right now
  # and possibly even the only arg is a plain label
  $b = Gtk2::Button->new ('hi');

this is do-able, but gets ugly and bloated in the implementation and required
documentation really quickly when you start applying it to every object in the
hierarchy.

so far, however, you can do

  $b = Gtk2::Button->new ('hi');

because you could do that in gtk-perl, too.  ;-)



> 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

to be brutally honest, i think that would be a horrible idea and i'm not
willing to do it.  the number (and names) of classes is set by Gtk+, not by
the perl bindings.  you'd have to learn a whole new interface, basically, and
all other Gtk+ documentation and tutorials would be no longer of any use.

also, the classes are all under the same namespace, so there's nothing to
worry about with namespace pollution.  also, they are one-to-one with the
classes defined by Gtk+ itself, so once you see an example of how the packages
map, you can guess at all the rest with high accuracy.


> (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.

"perl Makefile.PL PREFIX=/some/place" and an appropriate -I/path to perl at
runtime works for just about every module i've ever seen, including all
variants of gtk-perl.   thus you can install your dependecy modules without
actually having to install to a system-wide directory.  i do this for a lot of
specialty applications.



> > there.  just about everything you need to know.  what else?  =)
>
> Umm, can you write my program for me? That would be a big help...

depends.  would it take longer than an hour, and, if so, is there any money in
it, or maybe free food?  ;-)


-- 
muppet <scott asofyet org>