← Back to branch summary

~canonical-dx-team/ubuntu/maverick/gtk+2.0/menuproxy

« back to all changes in this revision

Viewing changes to docs/defsformat.txt

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2007-05-04 12:24:25 UTC
  • mfrom: (1.1.21 upstream)
  • Revision ID: james.westby@ubuntu.com-20070504122425-0m8midgzrp40y8w2
Tags: 2.10.12-1ubuntu1
* Sync with Debian
* New upstream version:
  Fixed bugs:
  - 379414 file chooser warnings when changing path in the entry
  - 418585 GtkFileChooserDefault sizing code is not DPI independent
  - 419568 Crash in search if start with special letter
  - 435062 build dies with icon cache validation
  - 379399 Segfault to call gtk_print_operation_run twice.
  - 387889 cups backend has problems when there are too many printers
  - 418531 invalid read to gtkicontheme.c gtk_icon_theme_lookup_icon...
  - 423916 crash in color scheme code
  - 424042 Segmentation fault while quickly pressing Alt+arrows
  - 415260 Protect against negative indices when setting values in G...
  - 419171 XGetVisualInfo() may not set nxvisuals
  - 128852 Gdk cursors don't look good on win32
  - 344657 Ctrl-H doesn't toggle "Show Hidden Files" setting
  - 345345 PrintOperation::paginate is not emitted for class handler
  - 347567 GtkPrintOperation::end-print is not emitted if it's cance...
  - 369112 gtk_ui_manager_add_ui should accept unnamed separator
  - 392015 Selected menu item invisible on Windows Vista
  - 399253 MS-Windows Theme Bottom Tab placement rendering glitches
  - 399425 gtk_input_dialog_fill_axes() adds child to gtkscrolledwin...
  - 403251 [patch] little memory leak in GtkPrintJob
  - 403267 [patch] memory leak in GtkPageSetupUnixDialog
  - 403470 MS-Windows Theme tab placement other than on top leaks a ...
  - 404506 Windows system fonts that have multi-byte font names cann...
  - 405089 Incorrect window placement for GtkEventBox private window
  - 405515 Minor leak in gtkfilesystemmodel.c
  - 405539 gdk_pixbuf_save() for PNG saver can return FALSE without ...
  - 415681 gdk_window_clear_area includes an extra line and column o...
  - 418219 GtkRecentChooser should apply filter before sorting and c...
  - 418403 Scroll to printer after selecting it from settings
  - 421985 _gtk_print_operation_platform_backend_launch_preview
  - 421990 gtk_print_job_get_surface
  - 421993 gtk_print_operation_init
  - 423064 Conditional jump or move depends on uninitialised value(s...
  - 423722 Fix printing header in gtk-demo
  - 424168 gtk_print_operation_run on async preview
  - 425655 Don't install gtk+-unix-print-2.0.pc on non-UNIX platforms
  - 425786 GDK segfaults if XineramaQueryScreens fails
  - 428665 Lpr Backend gets stuck in infinite loop during gtk_enumer...
  - 429902 GtkPrintOperation leaks cairo contextes
  - 431997 First delay of GdkPixbufAnimationIter is wrong
  - 433242 Inconsistent scroll arrow position calculations
  - 433972 Placing gtk.Expander inside a gtk.TextView() changes gtk....
  - 434261 _gtk_toolbar_elide_underscores incorrectly handles some s...
  - 383354 ctrl-L should make 'Location' entry disappear
  - 418673 gtk_recent_manager_add_item
  - 429732 gtk_accel_group_finalize accesses invalid memory
  - 435028 WM_CLIENT_LEADER is wrong on the leader_window
  - 431067 Background of the header window is not updated
  - 338843 add recent files support inside the ui manager
  - 148535 add drop shadow to menus, tooltips, etc. under Windows XP
* debian/control.in:
  - Conflicts on ubuntulooks (<= 0.9.11-1)
* debian/patches/15_default-fallback-icon-theme.patch:
  - patch from Debian, fallback on gnome icon theme

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/defsformat.txt
 
1
 
 
2
The overall syntax is:
 
3
 
 
4
     (type-of-thing-being-defined  name-used-to-refer-to-this-thing
 
5
       (attribute-name  attribute-value-depending-on-the-attribute)
 
6
       (attribute-name  attribute-value-depending-on-the-attribute)
 
7
       (attribute-name  attribute-value-depending-on-the-attribute))
 
8
 
 
9
Some definitions can have a c-declaration field that gives the C code
 
10
we parsed to arrive at the definition. The c-declaration is a quoted
 
11
string because it can contain parentheses and such.
 
12
 
 
13
Defined types and their attributes:
 
14
 
 
15
===
 
16
(module module-name
 
17
  (submodule-of module-name)) ;; submodule is optional
 
18
 
 
19
Ex: (module Gtk)
 
20
Ex: (module Rgb
 
21
      (submodule-of Gdk))
 
22
 
 
23
modules are later referred to with a list of module names, like 
 
24
(Gdk Rgb) or (Gtk)
 
25
 
 
26
Object and boxed type definitions automatically create a submodule.
 
27
For example, GtkCList creates the module (module CList (submodule-of
 
28
(Gtk))) which is referred to as module (Gtk CList).
 
29
 
 
30
===
 
31
 
 
32
(type
 
33
 (alias some-unique-identifier)
 
34
 (in-module module-name)   ;; optional, gchar* is not in a module
 
35
 (gtk-type-id gtk-type-system-id) ;; optional, absent if this is not
 
36
                                  ;; in the type system
 
37
 (is-parametric boolean)          ;; optional default to #f
 
38
 (in-c-name name-of-symbol-in-C)
 
39
 (out-c-name name-of-symbol-in-C)
 
40
 (inout-c-name name-of-symbol-in-C))
 
41
 
 
42
Ex: (type
 
43
     (alias string)
 
44
     (gtk-type-id GTK_TYPE_STRING)
 
45
     (in-c-name "const gchar*")
 
46
     (out-c-name "gchar**")      ;; actually I'm not sure how strings work out/inout
 
47
     (inout-c-name "gchar*"))
 
48
 
 
49
 (type
 
50
     (alias list)
 
51
     (gtk-type-id GTK_TYPE_POINTER)
 
52
     (is-parametric #t)
 
53
     (in-c-name "GList*")
 
54
     (out-c-name "GList**")
 
55
     (inout-c-name "GList**"))
 
56
 
 
57
 
 
58
 ;; This one would be implied by the (object) def for GtkWidget I
 
59
 ;; think - (type) is only required for types that are not implied
 
60
 ;; by other definitions, such as int/boolean/etc.
 
61
 
 
62
    (type
 
63
     (alias GtkWidget)
 
64
     (in-module (Gtk))
 
65
     (gtk-type-id GTK_TYPE_WIDGET)
 
66
     (in-c-name "GtkWidget*")
 
67
     (inout-c-name "GtkWidget*")
 
68
     (out-c-name "GtkWidget**"))
 
69
 
 
70
"Type" bindings are automatically assumed for objects, boxed types,
 
71
etc. as defined below.
 
72
 
 
73
The alias field is used to refer to the type later on.
 
74
 
 
75
Whenever a type alias can be used, it is also possible to use the
 
76
keyword "native", which implies that the type in question is too
 
77
C-specific to represent. Then a c-declaration will typically be
 
78
available for use.
 
79
 
 
80
C types containing [] or () are function pointers or arrays. For
 
81
arrays that don't specify a size, we just treat them as pointers. For
 
82
function pointers, we need special (type) syntax/attributes of some
 
83
kind, but since there basically aren't any of these right now in the
 
84
libs we care about we can just ignore them. For arrays that specify a
 
85
size ditto, you would handle them by adding an (array-size) attribute
 
86
or something or using the "native" keyword and skipping the (type)
 
87
stuff.
 
88
 
 
89
===
 
90
(object object-name
 
91
   (in-module module-name-list)
 
92
   (parent object-name optional-module-name-if-different)
 
93
   (abstract boolean-is-abstract-class) ;; omit for default of #f
 
94
   (c-name name-of-the-object-in-C)
 
95
   (field (type-and-name type-alias-of-struct-field name-of-struct-field)
 
96
          (access read-or-write-or-readwrite)))
 
97
   
 
98
 
 
99
Ex: (object Widget
 
100
      (in-module (Gtk))
 
101
      (parent Object)      ;; could say (parent Object (Gtk))
 
102
      (abstract #t)
 
103
      (c-name GtkWidget)
 
104
      (field (type-and-name GdkWindow* window) (access read)))
 
105
 
 
106
An "object" declaration automatically implies the type definition:
 
107
 
 
108
(type
 
109
  (alias concat-module-elements-and-object-name)
 
110
  (in-c-name pointer-to-c-name)
 
111
  (out-c-name pointer-to-pointer-to-c-name)
 
112
  (inout-c-name pointer-to-c-name))
 
113
 
 
114
Ex: 
 
115
 (type (alias GtkWidget) 
 
116
       (in-c-name GtkWidget*) 
 
117
       (out-c-name GtkWidget**) 
 
118
       (inout-c-name GtkWidget*))
 
119
 
 
120
It also implies a module that is the name broken into parts:
 
121
 (module CTree
 
122
   (submodule-of Gtk))
 
123
 
 
124
===
 
125
 
 
126
(function function-name
 
127
  (in-module module-name-list) ;; "static methods" go in their
 
128
                               ;;  object's module
 
129
  (is-constructor-of object-type-alias) ;; optional, marks a constructor
 
130
  (c-name function-name)
 
131
  (return-type return-value-type) ;; defaults to void
 
132
  (caller-owns-return boolean-value) ;; defaults to #f
 
133
  (can-return-null boolean-value) ;; defaults to #t
 
134
  (parameter in-or-out-or-inout 
 
135
      (type-and-name parameter-type-alias parameter-name)
 
136
      (type-parameter name-of-contained-type) ;; optional, requires parametric type
 
137
      (c-declaration "c-type-and-name")) ;; c-declaration only required
 
138
                                         ;; if the type alias is "native"
 
139
  (varargs #t) ;; has varargs at the end
 
140
)
 
141
 
 
142
Ex:
 
143
  (function init
 
144
    (in-module (Gdk Rgb)
 
145
    (c-name gdk_rgb_init)))
 
146
 
 
147
Ex: 
 
148
  (function new
 
149
    (in-module (Gdk Rgb Cmap))
 
150
    (is-constructor-of GdkRgbCmap)
 
151
    (c-name gdk_rgb_cmap_new)
 
152
    (return-type GdkRgbCmap)
 
153
    (caller-owns-return #t)   ;; perhaps this could be implied by is-constructor-of
 
154
    (parameter in (type-and-name array-of-guint32 colors))
 
155
    (parameter in (type-and-name gint n_colors)))
 
156
 
 
157
Ex:
 
158
  (function config_set_set_handler
 
159
   (in-module (Gnome))
 
160
   (c-name gnome_config_set_set_handler)
 
161
   (parameter in (type-and-name native func)
 
162
                 (c-declaration "void (*func)(void*)"))
 
163
   (parameter in (type-and-name gpointer data)))  
 
164
 
 
165
===
 
166
(method method-name
 
167
  (of-object object-name module-name)
 
168
  ;; retval/arg attributes as for (function), but with first parameter
 
169
  ;; omitted for non-constructors
 
170
   )
 
171
 
 
172
Ex:
 
173
  (method set_text
 
174
     (of-object Label (Gtk))
 
175
     (parameter (type-and-name const-gchar* str)))
 
176
 
 
177
===
 
178
(object-argument arg-name
 
179
   (of-object object-we-are-an-argument-of optional-objects-module)
 
180
   (type-id argument-type)       ;; GTK_TYPE_OBJECT etc.
 
181
   ;; flags all default to #f
 
182
   (readable bool-value)
 
183
   (writeable bool-value)
 
184
   (construct-only bool-value))
 
185
 
 
186
Ex:
 
187
  (object-argument label
 
188
     (of-object Label (Gtk))
 
189
     (type GTK_TYPE_STRING)
 
190
     (readable #t)
 
191
     (writeable #t))
 
192
 
 
193
=== 
 
194
(signal signal-name
 
195
  (run-action bool-value)
 
196
  (run-first bool-value)
 
197
  (run-last bool-value)
 
198
  (of-object object-we-are-a-signal-of optional-objects-module)
 
199
  ;; return value and parameters as for a function, omitting the object
 
200
  ;; and user data parameters
 
201
 
 
202
  ;; what other properties matter for a signal?
 
203
)
 
204
 
 
205
Ex:
 
206
  (signal select_row
 
207
     (of-object CList (Gtk))
 
208
     (run-first #t)
 
209
     ;; return type defaults to void
 
210
     (parameter in (type-and-name gint row))
 
211
     (parameter in (type-and-name gint column))
 
212
     (parameter in (type-and-name GdkEvent* event)))
 
213
 
 
214
=== 
 
215
(enum enum-name
 
216
  (in-module modname)
 
217
  (c-name name-in-c)
 
218
  (value (nick value-name-noprefixes-hyphen-lowercase) (c-name value-c-name)))
 
219
 
 
220
Ex:
 
221
 
 
222
  (enum DirectionType
 
223
    (in-module Gtk)
 
224
    (c-name GtkDirectionType)
 
225
    (value (nick tab-forward) (c-name GTK_DIR_TAB_FORWARD))
 
226
    (value (nick tab-backward) (c-name GTK_DIR_TAB_BACKWARD))
 
227
    (value (nick up) (c-name GTK_DIR_UP))
 
228
    (value (nick down) (c-name GTK_DIR_DOWN))
 
229
    (value (nick left) (c-name GTK_DIR_LEFT))
 
230
    (value (nick right) (c-name GTK_DIR_RIGHT)))
 
231
 
 
232
  (enum Pos
 
233
    (in-module (Gtk CTree))
 
234
    (c-name GtkCTreePos)
 
235
    (value (nick before) (c-name GTK_CTREE_POS_BEFORE))
 
236
    (value (nick as-child) (c-name GTK_CTREE_POS_AS_CHILD))
 
237
    (value (nick after) (c-name GTK_CTREE_POS_AFTER)))
 
238
 
 
239
===
 
240
(flags) is just like enum, but some bindings may wrap enums and flags differently.
 
241
    
 
242
===
 
243
 
 
244
(boxed boxed-name
 
245
  (in-module modname)
 
246
  (c-name c-name)
 
247
  (ref-func func-to-increase-refcount)
 
248
  (copy-func func-to-copy)
 
249
  (release-func func-to-destroy-or-decrement-refcount)
 
250
  (field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))
 
251
 
 
252
It is never OK to use memcpy() to copy a boxed type, or use
 
253
malloc()/free() to alloc/free one.
 
254
 
 
255
Ex:
 
256
 
 
257
 (boxed Pixmap
 
258
   (in-module (Gdk))
 
259
   (c-name GdkPixmap)
 
260
   (ref-func pixmap_ref)
 
261
   (release-func pixmap_unref))
 
262
 
 
263
An "object" declaration automatically implies the type definition:
 
264
 
 
265
(type
 
266
  (alias concat-module-elements-and-boxed-name)
 
267
  (in-c-name pointer-to-c-name)
 
268
  (out-c-name pointer-to-pointer-to-c-name)
 
269
  (inout-c-name pointer-to-c-name))
 
270
 
 
271
Ex: 
 
272
 (type (alias GdkPixmap) 
 
273
       (in-c-name GdkPixmap*) 
 
274
       (out-c-name GdkPixmap**) 
 
275
       (inout-c-name GdkPixmap*))
 
276
 
 
277
 
 
278
===
 
279
 
 
280
(struct struct-name
 
281
  (in-module modname)
 
282
  (c-name c-name)
 
283
  (field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))
 
284
 
 
285
Unlike a boxed type, a struct type can be copied with memcpy() and
 
286
allocated on the stack or with g_malloc().
 
287
 
 
288
Ex:
 
289
 (struct Rectangle
 
290
   (in-module (Gdk))
 
291
   (c-name GdkRectangle)
 
292
   (field (type-and-name gint16 x) (access readwrite))
 
293
   (field (type-and-name gint16 y) (access readwrite))
 
294
   (field (type-and-name guint16 width) (access readwrite))
 
295
   (field (type-and-name guint16 height) (access readwrite)))
 
296
 
 
297
Implies GdkRectangle type alias:
 
298
 
 
299
 (type (alias GdkRectangle) 
 
300
       (in-c-name GdkRectangle*) 
 
301
       (out-c-name GdkRectangle*)    ;; note - not the same as boxed types 
 
302
       (inout-c-name GdkRectangle*))
 
303
 
 
304
===
 
305
 
 
306
(user-function name
 
307
  (in-module module)
 
308
  (c-name c-typedef-name)
 
309
  ;; return-type and parameters as for (function)
 
310
)
 
311
 
 
312
Ex:
 
313
 
 
314
 (user-function PrintFunc
 
315
    (in-module (Gtk))
 
316
    (parameter in (type-and-name gpointer func_data))
 
317
    (parameter in (type-and-name gchar* str)))
 
318
 
 
319
===
 
320
 
 
321
(typedef new-name
 
322
  (in-module module)
 
323
  (c-name c-full-name)
 
324
  (orig-type alias-of-orig-type))
 
325
 
 
326
Ex:
 
327
 
 
328
 (typedef Type
 
329
   (in-module (Gtk))
 
330
   (c-name GtkType)
 
331
   (orig-type guint))
 
332
 
 
333
 
 
334
 
 
335
 
 
336
  
 
337
   
 
338