source: trunk/third/rep-gtk/README.gtk-defs @ 18404

-*-Indented-Text-*-

These notes describe the format of the .defs files


(import "DEFS-FILE")
(include "DEFS-FILE")



(define-enum ENUM-TYPEDEF-NAME
  (LISP-SYM CPP-MACRO)
  ...)



(define-flags FLAGS-TYPEDEF-NAME
  (LISP-SYM CPP-MACRO)
  ...)



(define-boxed BOXED-TYPEDEF-NAME
  ATTR ...)

where each ATTR is one of:

      (copy C-COPY-FUN)
      (free C-FREE-FUN)
      (size "C sizeof expression")
      (fields FIELD ...)

      where each FIELD is (TYPE-SYM NAME-SYM OPTIONS...)
      each OPTION may be `(setter t)' denoting that the field
      is settable. Also `(getter FUNCTION-NAME)' defining a custom
      method of retrieving the value



(define-object OBJECT-TYPEDEF-NAME (SUPER-CLASS-TYPEDEF)
  ATTR ...)

where each ATTR is one of:

      (fields FIELD ...)                [as above]



(define-func C-FUNC-NAME
  RETURN-VALUE [RET-OPTIONS...]
  (ARG ...)
  OPTIONS...)

where each ARG is (TYPE NAME-SYM [ARG-OPTIONS...)
and each OPTION may be one of:

  (scm-name ACTUAL-NAME-STRING)
  (protection ARG)                      ; gc protect callback for life of ARG
  (protection t)                        ; gc protect callback always
  (protection *result*)                 ; gc protect for life of RETURN-VALUE
  (undeferred t)                        ; no scm interrupt protection?
  (rest-arg t)                          ; last arg is &rest

and each ARG-OPTION may be one of:

  (= "default expression")
  (null-ok)                             ; allow nil
  (protect-during)

and each RET-OPTION may be one of:

  (copy nil)                            ; unimplemented?



(options OPTION ...)

where each OPTION can be:

      (includes "#include expression")
      (init-func "name of C function")
      (other-inits "name of C function" ... )
      (extra-init-code "code string")
      (provide FEATURE)

the `provide' option generates the rep dl stub required to provide
FEATURE and call the init-func when loaded



GTK fundamental types seem to include:

        invalid, none, char, bool, int, uint, long, ulong, float,
        string, enum, flags, boxed, foreign, callback, args, pointer,
        signal, c-callback, object

The guile-gtk .defs files seem to add the following:

        static_string, full_callback, file-descriptor, list, slist,
        double, SCM, cvec, cvecr, fvec, ret, tvec

static_string:
  a static string returned from a function

full_callback:
  a callback function used by the _full function variants (i.e.
  gtk_signal_connect_full). 

file-descriptor:
  an integer file descriptor

double:
  a double-precision float

SCM:
  a scheme object

(list TYPE [MODE]):
  a glib GList* (doubly-linked)

(slist TYPE [MODE]):
  a glib GSList* (singly-linked)

(cvec TYPE [MODE]):
  a counted-vector, stored in sgtk_cvec struct, in gtk_ function calls,
  it expands ``cvec.data, cvec.len''

(cvecr TYPE [MODE]):
  similar to cvec but expands ``cvec.len, cvec.data''

(fvec TYPE LEN [MODE]):
  similar to cvec but fixed length

(ret TYPE):
  similar to fvec but length is always one. used to mimic the C ``&foo''
  idiom of returning multiple values

(tvec TYPE [MODE]):
  zero-terminated vector

[ in the above, MODE is one of `in', `out' or `inout'. Defaults to `in' ]