1-*-Indented-Text-*-
2
3These notes describe the format of the .defs files
4
5(import "DEFS-FILE")
6(include "DEFS-FILE")
7
8
9(define-enum ENUM-TYPEDEF-NAME
10  (LISP-SYM CPP-MACRO)
11  ...)
12
13
14(define-flags FLAGS-TYPEDEF-NAME
15  (LISP-SYM CPP-MACRO)
16  ...)
17
18
19(define-boxed BOXED-TYPEDEF-NAME
20  ATTR ...)
21
22where each ATTR is one of:
23
24      (copy C-COPY-FUN)
25      (free C-FREE-FUN)
26      (size "C sizeof expression")
27      (fields FIELD ...)
28
29      where each FIELD is (TYPE-SYM NAME-SYM OPTIONS...)
30      each OPTION may be `(setter t)' denoting that the field
31      is settable. Also `(getter FUNCTION-NAME)' defining a custom
32      method of retrieving the value
33
34
35(define-object OBJECT-TYPEDEF-NAME (SUPER-CLASS-TYPEDEF)
36  ATTR ...)
37
38where each ATTR is one of:
39
40      (fields FIELD ...)		[as above]
41
42
43(define-func C-FUNC-NAME
44  RETURN-VALUE [RET-OPTIONS...]
45  (ARG ...)
46  OPTIONS...)
47
48where each ARG is (TYPE NAME-SYM [ARG-OPTIONS...)
49and each OPTION may be one of:
50
51  (scm-name ACTUAL-NAME-STRING)
52  (protection ARG)			; gc protect callback for life of ARG
53  (protection t)			; gc protect callback always
54  (protection *result*)			; gc protect for life of RETURN-VALUE
55  (undeferred t)			; no scm interrupt protection?
56  (rest-arg t)				; last arg is &rest
57  (gerror-arg t)				; last arg is GError arg
58
59and each ARG-OPTION may be one of:
60
61  (= "default expression")
62  (null-ok)				; allow nil
63  (protect-during)
64
65and each RET-OPTION may be one of:
66
67  (copy nil)				; unimplemented?
68
69
70(options OPTION ...)
71
72where each OPTION can be:
73
74      (includes "#include expression")
75      (init-func "name of C function")
76      (other-inits "name of C function" ... )
77      (extra-init-code "code string")
78      (provide FEATURE)
79
80the `provide' option generates the rep dl stub required to provide
81FEATURE and call the init-func when loaded
82
83
84GTK fundamental types seem to include:
85
86	invalid, none, char, bool, int, uint, long, ulong, float,
87	string, enum, flags, boxed, foreign, callback, args, pointer,
88	signal, c-callback, object
89
90static_string:
91  a static string returned from a function
92
93full_callback:
94  a callback function used by the _full function variants (i.e.
95  gtk_signal_connect_full).
96
97file-descriptor:
98  an integer file descriptor
99
100double:
101  a double-precision float
102
103SCM:
104  a scheme object
105
106(list TYPE [MODE]):
107  a glib GList* (doubly-linked)
108
109(slist TYPE [MODE]):
110  a glib GSList* (singly-linked)
111
112(cvec TYPE [MODE]):
113  a counted-vector, stored in sgtk_cvec struct, in gtk_ function calls,
114  it expands ``cvec.data, cvec.len''
115
116(cvecr TYPE [MODE]):
117  similar to cvec but expands ``cvec.len, cvec.data''
118
119(fvec TYPE LEN [MODE]):
120  similar to cvec but fixed length
121
122(ret TYPE):
123  similar to fvec but length is always one. used to mimic the C ``&foo''
124  idiom of returning multiple values
125
126(tvec TYPE [MODE]):
127  zero-terminated vector
128
129[ in the above, MODE is one of `in', `out' or `inout'. Defaults to `in' ]
130
131