doc/ref enchancement request!

[Ali Akcaagac <ali akcaagac stud fh-wilhelmshaven de>]

hello,

since a couple of days i'm dealing with the gtktree widget and finally i
decided to write here to request a tad more detailed documentation or
reference update for gtk+.

one of the more complicated sections i'm refering to is the iterator
explainations GtkTreeIter. in the example provided in the reference

.../gtk-doc/html/gtk/TreeWidget.html

it is explained that if you want to gtk_tree_store_set values in a
different row then you need to apply the child to its parent iterator

gtk_tree_store_append (store, &iter1, NULL); <-- the very first iter.
gtk_tree_store_append (store, &iter2, &iter1) <-- the child pointing to
                                                  its parent

now the problem here is that the reference shows an easy model where you
simply apply new code to the bottom for more children

gtk_tree_store_append (store, &iter3, &iter2) <-- the child pointing to
                                                  its parent

gtk_tree_store_append (store, &iter4, &iter3) <-- the child pointing to
                                                  its parent

and so on. this is for sure good to explain how it works, to make it
visible for those to learn more about the gtktree. but now let's assume,
and that's the issue i am hitting myself right now, that you don't know
how many children you need. let's say you want to deal with a filesystem
that has an unknown depth. you will agree to me that you can't hardcode
let's say 1000 children within the code. not to mention that this is in
no way readable and not to mention that this is not necessary. it would
be necessary (and this is my personal opinion here) to add a little
section that explains howto add a number of unknown iterations to such a
tree for easier understanding. here a little pseudocode example:

iter contains the value 10 for example telling you that you want to
store str1 into the 10th row of the store.

void iteration_set_value (guint        iter,
                          const gchar *str1);
{
  guint itercount = 1;
  const GtkTreeIter iter1 = NULL;
  const GtkTreeIter iter2 = NULL;

  while (itercount < iter) {
    itercount++;
    iter2 = iter1;
  }

  gtk_tree_store_append (?????,
                         &iter1,
                         &iter2);

  gtk_tree_store_set (store,
                      &iter1,
                      TITLE_COLUMN,
                      str,
                      -1);
}

oki something like this, i know this example is pure crap but this was
my first idea i got. i'm still dealing with the tree widget and right
now i hardcoded 10 iterations into my code which looks like crap too.
it's for sure a matter of time until i figure out a correct way in doing
this (by continue reading the gtk+ examples and the reference manual)
but for the long run it may be necessary to add such an example into the
reference or the tutorial (last named lacks explaination of the tree
completely). recursive retriving of values is no problem (once the tree
has been build) but building the tree with unknown iterations is a
problem. - at least right now as i see it (maybe it's unexpirience by
not enough reading of the api).

greets.

-- 
Name....: Ali Akcaagac
Status..: Student Of Computer & Economic Science
E-Mail..: mailto:ali akcaagac stud fh-wilhelmshaven de
WWW.....: http://www.fh-wilhelmshaven.de/~akcaagaa