GTK and LSB

["Wang, Yong Y" <yong y wang intel com>]

Hello

I've been working for LSB (Linux Standard Base) recently. LSB strives to develop and promote a set of standards that will increase compatability among Linux distributions and enable software applications to run on any compliant system.

A well supported standard for Linux is the necessary component to Linux's continued success. Without a commonly adopted standard, Linux will fragment, thus proving costly for ISVs to port their applications to the operating system and making it difficult for end users and Linux vendors alike. By adopting the Linux Standard Base, the Linux community provides this crucial portability so that applications can be used on more than one distribution of Linux with little or no change. With the LSB, all parties - distribution vendors, ISVs and end users -- benefit from a commonly supported version of Linux.

Recently a Desktop work group was formed within LSB project and this subcommittee will focus on standardizing libraries needed by desktop applications. GTK+ has been identified as a candidate for future inclusion in LSB. See http://www.linuxbase.org/futures/candidates/gtk2/index.html for details. For standardizing a library, we have two things to do basically. One is to write specification for the library. The other is the development of test suites for runtimes. For the test suite development, we have evaluated GTKVTS project which can be found in GNOME CVS.

Since there are a huge number of functions exported by GTK+ libraries, including gtk, gdk, glib, gobject, atk and pango, etc, it's impossible to test them all given the resources we have so far. Therefore we identified 30 most popular applications built on GTK+, like GIMP and Evolution, to collect real world data about which set of functions are most heavily used so that we can begin to work on them first.

Unfortunely, we found some of the most heavily used functions are not covered by the existing API documentation. The gtk_*_get_type family of functions are of this kind, including gtk_container_get_type, gtk_box_get_type, etc. Are there any reasons why they are undocumented?

I found all these gtk_*_get_type functions look similar at source code level. The template is outlined below:

GType
gtk_foo_get_type (void)
{
  static GType foo_type = 0;

  if (!foo_type)
    {
      static const GTypeInfo foo_info =
      {
        sizeof (GtkBoxClass),
        NULL,           /* base_init */
        NULL,           /* base_finalize */
        (GClassInitFunc) gtk_foo_class_init,
        NULL,           /* class_finalize */
        NULL,           /* class_data */
        sizeof (GtkFoo),
        0,              /* n_preallocs */
        (GInstanceInitFunc) gtk_foo_init,
        NULL,           /* value_table */
      };

      foo_type = g_type_register_static (GTK_TYPE_PARENT_OF_FOO, "GtkFoo",
                                         &foo_info, flags);	/* flags depends on the traits of type foo */
    }

  return foo_type;
}

As we can see from the above code, what the function gtk_foo_get_type returns depends on another function g_type_register_static which is from gobject library. Below is the existing documentation for this function.

GType       g_type_register_static          (GType parent_type,
                                             const gchar *type_name,
                                             const GTypeInfo *info,
                                             GTypeFlags flags);

Registers type_name as the name of a new static type derived from parent_type. The type system uses the information contained in the GTypeInfo structure pointed to by info to manage the type and its instances (if not abstract). The value of flags determines the nature (e.g. abstract or not) of the type. 

parent_type :	Type which this type will be derived from. 	
type_name : 	0-terminated string used as the name of the new type. 	
info :	 	The GTypeInfo structure for this type. 	
flags :		Bitwise combination of GTypeFlags values. 	
Returns : 	The new type identifier.	

But from the existing documentation, we cannot get any success indicator. The last sentence (i.e. Returns :The new type identifier.) does not provide such information. I have read the source code of g_type_register_static and it seems like this function will return 0 if an error occurred. Is there anyone who can tell whether I understand correctly or not?

Another observation of mine is that the existing documentation always include a class hierarchy for these types. Let's take GtkContainer as an example.

  GObject
   +----GtkObject
         +----GtkWidget
               +----GtkContainer
                     +----GtkBin
                     +----GtkBox
                     +----GtkCList
                     +----GtkFixed
                     +----GtkPaned
                     +----GtkIconView
                     +----GtkLayout
                     +----GtkList
                     +----GtkMenuShell
                     +----GtkNotebook
                     +----GtkSocket
                     +----GtkTable
                     +----GtkTextView
                     +----GtkToolbar
                     +----GtkTree
                     +----GtkTreeView

>From this hierarchy, we can get the following information: 
GtkContainer is a classed type, rather than a fundamental type like gchar, gint or gdouble, etc.
GtkContainer is a derived type (derived from GtkWidget).
GtkContainer is a derivable type. It can be further derived by GtkBox and GtkTable, etc.
The direct parent type of GtkContainer is GtkWidget.
etc.

The gobject library provides corresponding functions to test these qualifications as listed below.

G_TYPE_IS_CLASSED
G_TYPE_IS_DERIVED
G_TYPE_IS_DERIVABLE
g_type_parent
etc.

Test cases can be developed accordingly. But I'm not sure whether these qualifications are enough to test these gtk_*_get_type functions.

I wonder what do you guys think are the success indicators for gtk_*_get_type functions.
Any comment or advice is welcome.



Thanks
Yong Wang