<< Prev | - Up - | Next >> |
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.)
GTK+ is organized into the following modules:
GDK at 'x-oz://system/gtk/GDK'
GTK at 'x-oz://system/gtk/GTK'
GTKCANVAS at 'x-oz://system/gtk/GTKCANVAS'
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.
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 classNameGetField
FieldName 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.
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 |
---|---|
| int |
|
|
| int |
| float |
enumerations, flags | integer |
| virtual string |
| list of virtual strings |
| record |
| list of objects |
| list of four floats |
all other pointers (i. e., | 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.
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 |
---|---|---|---|---|
|
|
| object |
|
| foreign pointer |
|
|
|
| foreign pointer |
|
|
|
Figure 3.2: Manually Managed Data Structures
For details on how to use these, refer to Chapter 4.
Due to implementation limitations, not all functions are fully supported: All functions using arrays of GtkArg
s 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.
<< Prev | - Up - | Next >> |