SimpleList.pm and activation callbacks (patch)

[Nathan Kurz <nate verse com>]

[This is a resend from a week agao as the original seems to have been
lost because I didn't wait long enough subscribing before sending.  I
just saw people's messages about progress on the tutorial---great!]

Hello ---

I'm new to this list, and I thought I'd offer some thoughts on my
experience of getting started with Gtk2.  I'm very experienced with
Perl, did a little bit a long time ago with Perl-Tk, and otherwise
have no experience with Gtk+ or similar toolkits.

I started last week trying to write a small "patch tracker" program
that would keep track of patches in progress, allowing them to be
applied, unapplied, and checked in to CVS, and so forth.  Perl-Tk was
the only Perl graphical toolkit I'd heard of, so I started with it.

Generally, Perl-Tk worked great: pretty easy to install from CPAN,
good documentation, and lots of code fragments and examples to start
with.  But no matter what I did, my code was hideously ugly.  I just
couldn't get used to the strange, inverted OO, dash-heavy syntax.

So I went searching for another solution, and found Gtk-Perl.
Unfortunately, it wasn't sufficiently clear to me initially that
Gtk-Perl was deprecated, that I really should be using Gtk2-Perl.
Maybe the page at <http://www.gtkperl.org/> could be edited to include
some forward mention of the existence of Gtk2-Perl?

Once I figured out that I wanted Gtk2-Perl, things got smoother.  The
source install from CPAN worked perfectly, once I figured out that I
needed to install the ExtUtils stuff first.  And once it was
installed, the "hello world" example from
<http://gtk2-perl.sourceforge.net/doc/intro/> worked as soon as I
pasted it in.  The next couple example programs on that page worked
too, and by staring at them I was able to figure out the basics.

Things got harder after that, though.  I started with the old Gtk-Perl
tutorial and the Gtk-C tutorial, but really was wanting to have some
code samples to use as examples. It took me a while to find the
/example directory in the source distribution, and then even longer
(until I was reading the mailing list archives) to find the /gtk-demo
stuff.  It would help if these could be made more prominent:  in the
README file, on the Documentation page, or even as a couple lines
printed out at the end of the "make install" process.

Since then, I've been going faster, but still in fits and starts.
Lacking the proper Gtk terminology, I find it really hard to find out
how to do simple things.  For example, I wanted to "disable" some
buttons, and it took me 30 minutes of searching and reading to figure
out that I needed to call "set_sensitive".  And even then, I couldn't
find an example: I was really surpised when it actually worked!

A lot of the problem is the object hierarchy of the widgets.  The API
docs have complete information, but lacking an example I just don't
know where to look.  Using the set_sensitive example, nowhere under
"Gtk2::Button" does it tell me that set_sensitive is an option.  One
has to work one's way up the hierarchy, searching for what one is
looking for, made harder because one doesn't know what it will be
called.  Maybe there could be something like the "Object Browser"
program (which I found when searching for examples) that could simply
show all the possible methods for each widget, with a simple
explanation of what each method does?

Basically, my experience so far has been that the code works great,
the documentation that is present is good, but that actually figuring
out how to do anything new is pretty difficult.  The main thing I find
myself wanting are more sample code, more sample programs, and more
working examples.  After that, a more complete tutorial would be
great.  But I'd settle for more well commented sample programs.

I mention these things not because you all have nothing better to do
and are waiting for my orders, but just to give you a perspective on
how the current stuff looks to a new user starting to use the project.
I understand quite well why you might choose to work on the parts that
are of more benefit to you, the advanced users, rather than on the
parts that you have no personal need for.

Anyway, enough talk.  Here's a tiny patch that might make
SimpleList.pm a little easier to use.  I found making a list really
simple, but handling the activate callback necessitated learning about
a number of details about the MVC approach (models, get_iter(),
TreePath's, etc).  This patch adds a function to SimpleList that users
can call from that callback function so they don't need to figure all
that out.  It also gives an example of how it is used.

Thanks for making Gtk2 work!

Nathan Kurz
nate verse com

---------------------- cut here ---------------------------------

--- SimpleList.pm.orig  2004-03-02 17:21:48.000000000 -0700
+++ SimpleList.pm       2004-03-02 18:41:13.000000000 -0700
@@ -219,6 +219,20 @@
        @{$_[0]->{data}} = @{$_[1]};
 }
 
+sub data_row_from_path {
+       my ($self, $path) = @_;
+
+       # $path->get_depth always 1 for SimpleList
+       # my $depth = $path->get_depth;
+
+       # array has only one member for SimpleList
+       my @indices = $path->get_indices;
+       my $index = $indices[0];
+       
+       return $self->{data}->[$index];
+}
+
+
 ##################################
 package Gtk2::SimpleList::TiedRow;
 
@@ -469,8 +483,16 @@
 
   # Gtk2::SimpleList is derived from Gtk2::TreeView
   $slist->set_rules_hint (TRUE);
-  $slist->signal_connect (row_activated => \&row_clicked);
 
+  # callbacks do not require knowledge of TreeView details
+  $slist->signal_connect (row_activated => \&row_clicked);
+  sub row_clicked {
+          my ($slist, $path, $column) = @_;
+          my $row_ref = $slist->data_row_from_path ($path);
+          my $clicked = $row_ref->[$column];
+          print "You clicked '$clicked'\n";
+  }       
+          
   # turn an existing TreeView into a SimpleList; useful for
   # Glade-generated interfaces.
   $simplelist = Gtk2::SimpleList->new_from_treeview (
@@ -546,6 +568,12 @@
 and for those programmers who don't like to type-cast and have static, set once
 data.
 
+=item $slist->data_row_from_path (path)
+
+A reference to the data row to which the callback's $path argument refers.
+Identical to $slist->{data}->[($path->get_indices())[0]],
+but significantly easier to remember.
+
 =item @indices = $slist->get_selected_indices
 
 Return the indices of the selected rows in the ListStore.


----- End forwarded message -----