To Jonathan - GtkTreeView

[Brian Cameron <Brian Cameron Sun COM>]

GtkTreeView experts:

I am now working to implement the ATK interfaces for the GtkTreeView
widget.  I wanted to share with you our ideas of how to implement
this and ask some questions so I fully understand how this widget
works.

First of all, we believe that it will likely be necessary for each
Model to implement its own ATK implementation.  For example, the
GtkListStore would clearly be best represented by implementing it
as an AtkTable.  However, the AtkTable interface may not work so
well with the GtkTreeStore.  People who create their own custom
stores will likely need to implement their own ATK interfaces if
they want them to be accessible.

For your reference if you want to review the AtkTable interface, it
can be seen here:

   http://developer.gnome.org/doc/API/2.0/atk/atk-atktable.html
   
Specifically talking about the implementation for GtkListStore:

1. The function ref_at

   This function returns an AtkObject which corrisponds to the cell
   value.  If the cell contains multiple objects, the AtkObject that
   is returned will be a "composite" AtkObject which contains each
   object that is in the cell.  No real concerns here.
   
2. There are functions atk_table_get_n_cols and atk_table_get_n_rows.

   There isn't an accessor function for getting the number of columns,
   so do I have to call the gtk_tree_view_get_columns and loop over 
   them myself and count them?   It would be convenient if
   tree_view->priv->columns were made publically available.
   
   There also isn't an accessor function for getting the number of
   rows?  For the ListStore should I just create an Iterator for
   column 0 and loop until I get to the end, counting as I go?  This
   seems a bit ugly, but possible.
   
   I'm assuming that for a TreeStore that the concept of rows/cols
   doesn't make any sense.

3. The functions atk_table_get_index_at, atk_table_get_row_at_index,
   and atk_table_get_column_at_index give the AT the ability to loop
   over all the cells in a linear fashion.  We are currently thinking
   of generating this index as follows:
   
     index = (# of cols) * (col #) + (row #).
     
   Then to get the row & column numbers from the index you just do
   the following:
   
     row = (int) (index % (# of cols))
     col = (int) (index / (# of cols))
   
   It is expected that the index becomes invalid if/when the number
   of rows or columns changes.  The ATK interface exports properties
   and/or signals that will notify the user of when such thing
   happens.
   
   I don't really have any question about this, but just wanted to 
   share this idea with you and verify it sounds reasonable to you.

4. The functions get_caption, set_caption, get_column_description,
   set_column_description, get_row_description, set_row_description,
   get_summary, and set_summary
   
   A "caption" is intended to be a brief title of the table.
   A "column_description" is a verbose description of each column.
   A "row description" is a verbose description of each row.
   A "summary" is a verbose description of the table.  Think of it
      as like the "altname" of an image.  In real life it is sometimes
      used to try to summarize the purpose & useful data that is in
      the table.

   I am assuming that the idea of a "row description" is meaningless
   to both ListStore and TreeStore.  Is this correct?
   
   Otherwise, does GtkTreeView support these constructs?  If not we
   can implement them solely in ATK.  This would mean that a person
   who is setting up a specific table would call the ATK setter
   functions so that the values could be accessed from an AT reader.
   
   However, if GtkTreeView supports, say tooltip descriptions of each 
   column, it might make sense to use that as the column description.
   It might be a little cleaner if the programmer who is building a 
   table set these values with the GtkWidget directly rather than
   with ATK.
   
   So the main question is what support does GtkTreeView provide for
   the concept of caption, column description, row description, and/or
   summary?

5. get_column_header, get_row_header

   These functions return the AtkObject that corrisponds to the row
   or column header.  If the column header is a button, it would return
   the AtkObject that corrisponds to that button.  If it is a label, it
   would return the AtkObject that corrisponds to that label.
   
   I believe that the idea of a "row header" is meaningless to both
   ListStore and TreeStore.  Is that correct?
   
6. get_column_extant_at, get_row_extant_at.

   These functions are to deal with HTML like tables where a cell can
   "extend" into another row or column.  Like this (exciting text
   graphics follow):
   
    #0 #1 #2 #3
    ___________
   |__|__|__|__|
   |__|_____|__|   <- an example of a cell that extends columns #1 & #2
   |__|__|__|__|
   |  |__|__|__|   { an example of a cell that extends into two rows
   |__|__|__|__|   { (in column #0)
   
   I don't believe GtkTreeView supports such cells.  Is this the case?
   
7. get_selected_columns, get_selected_row, is_column_selected, is_row_selected,
   is_selected
   
   It is my understanding that only rows can be selected in GtkTreeView.
   Is this correct?

Lastly, I would be interested to hear other opinions regarding whether
it makes sense to implement the TreeStore's ATK interface as an AtkTable.
In other words, would it be useful to be able to access a TreeStore
using the methods described above.  The alternative is to make trees
accessible in the same way that it is done in Java.  This method
uses the representation of a tree of container objects with
parent/child relationships and lets the AT vendor dig through them
in this way. 
   
Thanks!

Brian