3 How the C API is mapped to Oz

This chapter describes the details on how the C API is mapped to Oz. This knowledge is required when you want to make use of the original reference documentation at http://www.gtk.org/api/ with the binding. (For the canvas, the documentation is at http://developer.gnome.org/doc/API/libgnomeui/; only look at the GnomeCanvas, GnomeCanvasItem and GnomeCanvasGroup widgets.)

3.1 Modules

GTK+ is organized into the following modules:

Each module represents a namespace. The corresponding API constants and functions are mapped to constants and classes and class methods in these namespaces. The Oz class hierarchy corresponds to the widget hierarchy.

Toplevel Functions

Note that toplevel C functions are also mapped to methods of the appropriate classes. Since Oz has no static methods, it may be necessary in practice to create a dummy object using the noop constructor to call them. The noop constructor does not actually create a widget.

3.2 Name Translation

We will illustrate how C structure fields and C functions are mapped to methods by an example. Consider the C API for GtkButton, which is derived from GtkBin:

/* fields */ 
struct _GtkButton {
  GtkBin bin;
  GtkWidget *child;
  guint in_button : 1;
  guint button_down : 1;
  guint relief : 2;
};
/* constructors */ 
GtkWidget *gtk_button_new();
GtkWidget *gtk_button_new_with_label 
           (const gchar *label);
/* signal emitters */ 
void gtk_button_pressed(GtkButton *button);
void gtk_button_released(GtkButton *button);
void gtk_button_clicked(GtkButton *button);
void gtk_button_enter(GtkButton *button);
void gtk_button_leave(GtkButton *button);
/* attribute accessors */ 
void gtk_button_set_relief 
     (GtkButton *button, GtkReliefStyle newstyle);
GtkReliefStyle gtk_button_get_relief(GtkButton *button);

This is mapped an Oz class as follows:

class GTK.button from GTK.bin 
   %% fields
   meth buttonGetFieldBin(?Bin)
   meth buttonGetFieldChild(?Widget)
   meth buttonGetFieldInButton(?I)
   meth buttonGetFieldButtonDown(?I)
   meth buttonGetFieldRelief(?I)
   %% constructors
   meth new()
   meth newWithLabel(Label)
   %% signal emitters
   meth pressed()
   meth released()
   meth clicked()
   meth enter()
   meth leave()
   %% attribute accessors
   meth setRelief(ReliefStyle)
   meth getRelief(?ReliefStyle)
end

General Scheme

The general scheme is that all underscored identifiers are translated to use camel-casing. Since classes belong to a module and methods belong to a class, the module and class name prefixes are cut off to increase readability. The first letter of method labels is downcased to allow to use convenient Oz atom syntax.

Field Accessors

Field accessors are also camel-cased, but in contrast to the standard methods, they use the classNameGetFieldFieldName pattern. For example, the button_down field above is read using the buttonGetFieldButtonDown accessor method of the class GTK.button. Fields cannot be written to directly.

Constants

The members of enumerations and flags are translated to constants exported with all upper case names containing underscores, with the module prefix cut off.

3.3 Types

Figure 3.1 shows the mapping of the C types onto Oz types. Values are converted back and forth transparently, preserving identity whenever possible.


C Type

Oz Type

gint, guint, glong, gulong

int

gboolean

false and true

gchar, guchar

int

gfloat, gdouble

float

enumerations, flags

integer

gchar *, guchar *

virtual string

gchar *[], guchar *[]

list of virtual strings

GdkEvent *

record

GList *

list of objects

double[4]

list of four floats

all other pointers (i. e., GtkWidget *)

object

Figure 3.1: C to Oz Type Translation


Flags

Flags are translated to integer constants. In general, several constants can be combined using addition (+).

Inout Arguments

The int * and double * types are considered to be inout arguments. They are mapped to pairs XIn#XOut where XIn is the value at the time the function is called and XOut will be bound to the value assigned by the function.

Gdk Events

Where a GDK event (a value of the GdkEvent union type) appears as argument to a callback, a record is constructed using the label to indicate which member it belongs to. The features of the record represent the corresponding event structure members.

3.4 Memory Management

GTK+ and GDK use reference counting garbage collection for most of their datastructures, and the binding safely keeps up this property for those items.

Manual Management

Some data, however, needs manual allocation and deallocation by the user. These types are shown in Figure 3.2.


C Type

Oz Type

Constructor

Accessor

Destructor

GdkImlibImage *

GDK.imlibImage

GDK.imlib,loadImage

object

destroyImage method

GtkArg *

foreign pointer

GTK.makeArg

GTK.getArg

GTK.freeArg

gchar *[], guchar *[]

foreign pointer

GTK.makeStrArr

GTK.getStrArr

GTK.freeStrArr

Figure 3.2: Manually Managed Data Structures


For details on how to use these, refer to Chapter 4.

3.5 Limitations

Due to implementation limitations, not all functions are fully supported: All functions using arrays of GtkArgs and all variable argument versions of those functions support only a single argument. This usually only results in performance loss (not loss of expressivity) since most of these functions can be called iteratively.


Thorsten Brunklaus and Leif Kornstaedt
Version 1.3.1 (20040823)