update of defs file

[Ariel Rios <ariel linuxppc org>]

I have removed some of the comments now that hp has cleared
things me out =)

I have also added the null-ok part I have missed

And, I have added a syntax section that should clarify things =)

ariel


Authors:
Havoc, James, Ariel

Revision 3.1

SYNTAX
------

The overall syntax is:

     (define-type-of-thing  name-used-to-refer-to-this-thing
       (attribute-name  value-depending-on-attribute+ . value-depending-on-attribute*)+)

+value-depending-on-attribute can be 

Scheme like data-types:

-string : Sequence of characters enclosed with double quotes [quotes inside 
          a string are written by escaping it with a backslash (\).]

-number : Sequence of numerical values

-boolean : Standard boolean objects are written as #t and #f

Some attribute may take the special variable:

-null-ok : Which means that a NULL value can be passed or returned.

Finally, a value-depending-on-attribute can also be:

-Another (atrribute-name value-depending-on-attribute) 
-Any given number of value-depending-on-attribute

+Notes about notation:

- * :
Means 0 or more ocurrences

- + :
At least one ocurrence

- Optional arguments:
 Whenever the following form is found:
 (id val1 . val2)
 it implies that val2 is an optional value.

- Comments:
 Handled using scheme comments syntax:

;; This is a comment

--------------

Defined types and their attributes:

========
GModules

(gmodule module-name) 

Eg: 
  (gmodule "Gtk")
Eg: 
  (gmodule "GdkRgb")

====
TYPES

(define-type new-type
  (c-name name) 
  (g-type-id gtk-type-system-id))

(define-type string
  (c-name "gchar *")
  (g-type-id "G_TYPE_STRING"))

==========
INTERFACES
   
(define-interface Editable
  (in-module module-name)
  (c-name name-of-the-c-interface))
    
Eg.
(define-interface Editable
 (in-module "Gtk")
 (c-name "GtkEditable"))

====
OBJECTS

(define-object object-name
   (in-module module-name)
   (parent object-name)
   (c-name name-of-the-object-in-C)
   (abstract boolean) ;;defaults to #f
   (implements name-of-interface) ;;defaults to #f
   (fields 
          (alias-of-struct-field name-of-struct-field access)*))
   
Eg: (define-object Widget
      (in-module "Gtk")
      (parent "GtkObject")     
      (c-name GtkWidget)	       
      (abstract #t)   
      (fields 
         ("GdkWindow *" "window" "read"))))

Eg:

(define-object Entry
  (in-module "Gtk")
  (parent "GtkWidget")
  (c-name "GtkEntry")
  (implements "GtkEditable"))


=========
FUNCTIONS

(define-function function-name
  (in-module module-name-list) ;; "static methods" go in their objects's module
  (is-constructor-of object-type-alias) ;; bool, marks a constructor defaults to #f
  (c-name function-name)
  (return-type return-value-type) 
  (caller-owns-return boolean-value) ;; defaults to #f
  (can-return-null boolean-value) ;; defaults to #t
  (fields
      (in-or-out parameter-type-alias parameter-name . c-name)*)
  (varargs #t) ;; has varargs at the end
)

Eg:
  (define-function init
    (in-module "GdkRgb")
    (c-name "gdk_rgb_init")
    (fields ()))

Eg: 
  (define-function new
    (in-module "GdkRgbCmap")
    (is-constructor-of "GdkRgbCmap")
    (c-name "gdk_rgb_cmap_new")
    (return-type "GdkRgbCmap")
    (caller-owns-return #t)   ;; perhaps this could be implied by is-constructor-of
    (fields 
        (in "array-of-guint32" "colors")
        (in "gint" "n_colors")))

Eg:
  (define-function config_set_set_handler
   (in-module "Gnome")
   (c-name "gnome_config_set_set_handler")
   (fields 
       (in "native" "func" "void (*func)(void*)")
       (in "gpointer" "data")))

=======
METHODS

/*
	Cant' we just handle methods with define-func
        and just add a field called,
        (is-method bool) ???
*/

     
(define-method method-name
  (c-name c-name)
  (of-object object-name)
  ;; retval/arg attributes as for (function), but with first parameter
  ;; omitted for non-constructors
   )
 
Eg:
  (define-method set_tEgt
     (c-name "gtk_label_set_tEgt")
     (of-object "Label")
     (fields 
         ("const-gchar*" "str")))
     
===============
OBJECT ARGUMENTS

(define-object-argument arg-name
   (of-object object-we-are-an-argument-of optional-objects-module)
   (type-id argument-type)       ;; GTK_TYPE_OBJECT etc.
   ;; flags all default to #f
   (readable bool-value)
   (writeable bool-value)
   (construct-only bool-value))

Eg:
  (define-object-argument label
     (of-object Label "Gtk")
     (type "GTK_TYPE_STRING")
     (readable #t)
     (writeable #t))

======= 
SIGNALS

(definal-signal signal-name
  (of-object object-we-are-a-signal-of)
  (run-action bool-value)
  (run-first bool-value)
  (run-last bool-value)
  (parameters
      (in-or-out parameter-type-alias parameter-name . c-name)*))

Eg:
  (define-signal select_row
     (of-object "CList")
     (run-first #t)
     ;; return type defaults to void
     (parameters
         (in "gint" "row")
         (in "gint" "column")
         (in "GdkEvent *" "event")))

===== 
ENUMS

(define-enum enum-name
  (in-module modname)
  (c-name name-in-c)
  (values
     (value-c-name numval)*)

Eg:

  (define-enum DirectionType
    (in-module "Gtk")
    (c-name "GtkDirectionType")
    (values 
       ("tab-forward" "GTK_DIR_TAB_FORWARD" 0)
       ("tab-backward" "GTK_DIR_TAB_BACKWARD" 1)
       ("up" "GTK_DIR_UP" 2)
       ("down" "GTK_DIR_DOWN" 3)
       ("left" "GTK_DIR_LEFT" 4)
       ("right" "GTK_DIR_RIGHT" 5)))

  (define-enum Pos
    (in-module "GtkCTree")
    (c-name "GtkCTreePos")
    (values 
       ("before" "GTK_CTREE_POS_BEFORE")
       ("as-child" "GTK_CTREE_POS_AS_CHILD")
       ("after" "GTK_CTREE_POS_AFTER")))

=====
FLAGS
 
Just like enum, but some bindings may wrap enums and flags differently.
    
===========
BOXED TYPES

(define-boxed boxed-name
  (in-module modname)
  (boxed-c-name c-name)
  (ref-func func-to-increase-refcount c-name)
  (copy-func func-to-copy c-name)
  (release-func func-to-destroy-or-decrement-refcount c-name)
  (fields 
     (type-alias-of-struct-field name-of-struct-field access-rule)*))


Eg:

 (define-boxed Pixmap
   (in-module "Gdk")
   (boxed-c-name "GdkPixmap")
   (ref-func "pixmap_ref" "gdk_pixmap_ref")
   (release-func "pixmap_unref" "gdk_pixmap_unref"))




===
STRUCTS

(define-struct struct-name
  (in-module modname)
  (c-name c-name)
   (fields 
     (type-alias-of-struct-field name-of-struct-field access-rule)*))

Unlike a boxed type, a struct type can be copied with memcpy() and
allocated on the stack or with g_malloc().

Eg:
 (define-struct Rectangle
   (in-module "Gdk")
   (c-name "GdkRectangle")
   (fields 
      ("gint16" "x" "readwrite")
      ("gint16" "y" "readwrite")
      ("guint16" "width" "readwrite")
      ("guint16" "height" "readwrite")))



==============
USER-FUNCTIONS

(define-user-function name
  (in-module module)
  (c-name c-typedef-name)
  ;; return-type and parameters as for (function)
)

Eg:

 (define-user-function PrintFunc
    (in-module "Gtk")
    (parameters 
        (in "gpointer" "func_data")
        (in "gchar *" "str")))

=======
TYPEDEF

(define-typedef new-name
  (in-module module)
  (c-name c-full-name)
  (orig-type alias-of-orig-type))

Eg:

 (define-typedef Type
   (in-module "Gtk")
   (c-name "GtkType")
   (orig-type "guint"))