1GOB2(1) General Commands Manual GOB2(1)
2
6 GOB2 - The GObject Builder
7
9 gob2 [ option ] ... file
10
13 GObject Builder is a simple preprocessor for easily creating GObject
14 objects. It does not parse any C code and ignores any C errors. It is
15 in spirit similar to things like lex or yacc. In some ways it also
16 resembles java. But it is really just a simple preprocessor for creat‐
17 ing GObjects for use in C or C++ and it is not a programming language.
18
21 -? -h --help
22 Display a simple help screen.
23 --version
25 Display version information
26 -w --exit-on-warn
28 Exit with an error code even when you encounter a warning.
29 --no-exit-on-warn
31 Exit with an error only on errors, not on warnings, this is the
32 default.
33 --for-cpp
35 Generate C++ code.
36 --no-extern-c
38 Never add the extern "C" to the header.
39 --no-gnu
41 Never generate any code with GNU C extensions. However all the
42 GNU C extensions are always wrapped in #ifdef __GNUC__, so code
43 using them compiles correctly even on non-GNU compilers. This
44 option is for purists only. (using GNU extensions some warnings
45 are eliminated, some ugly hacks and there is better argument
46 type safety, so it´s good to use them)
47 --no-touch
49 Don´t touch output files unless they really changed (implies
50 --no-touch-headers). Be careful with automake, see section PRE‐
51 VENTING SPURIOUS BUILDS.
52 --no-touch-headers
54 Don´t touch the generated header file unless it really changed,
55 this avoids spurious rebuilds, but can confuse some make systems
56 (automake in particular), so it is not enabled by default. Pri‐
57 vate header is still touched even if unchanged however.
58 --always-private-header
60 Always create a <basename>-private.h file, even if it would be
61 empty.
62 --ondemand-private-header
64 Create the private header only if it would have something in it,
65 that is, if there are some private data members or protected
66 methods. This is the default.
67 --no-private-header
69 Never create a private header file. If we use any private data
70 members, define the private data structure at the point in the
71 .c source where the class definition begins.
72 --m4 Preprocess source with m4. Following args will be passed to m4.
74 --m4-dir
76 Print directory that will be searched for m4 files.
77 -n --no-write
79 Do not write any output files, just check syntax of the input
80 file.
81 --no-lines
83 Do not print out the ´#line´ statements into the output. Useful
84 for debugging the auto-generated generated code.
85 --no-self-alias
87 Do not create the Self and SelfClass type aliases and the SELF,
88 IS_SELF and SELF_CLASS macros.
89 --no-kill-underscores
91 Do not remove the initial underscore from method names.
92 --always-private-struct
94 Always include the private pointer in the public header file.
95 This is useful for files which are part of a library and you
96 want to reserve the right to add some private data members with‐
97 out breaking binary compatibility.
98 -o --output-dir
100 The directory into which output should be placed.
101 --file-sep[=c]
103 Replace default `-´ file name separator. If no separator char‐
104 acter is given then none is used. Only one character can be
105 used.
106
109 Because we need to parse out different parts of the typename, sometimes
110 you need to specify the typename with some special syntax. Types are
111 specified in capitalized form and words are separated by `:´. The
112 first word of the type (which can be empty) is the "namespace". This
113 fact is for example used for the type checking macro and the type
114 macro. For "Gtk:New:Button", the macros will be GTK_IS_NEW_BUTTON and
115 GTK_TYPE_NEW_BUTTON. This colon separated format of typenames is used
116 in the class declaration header and for method argument types.
117
120 The filenames are created from the typename. The words are separated
121 by `-´ (this can be changed with --file-sep option) and all in lower
122 case. For example for an object named "Gtk:New:Button", the files are
123 gtk-new-button.c and gtk-new-button.h. If you are using C++ mode, the
124 output .c file will in fact be a .cc file. If you have any private
125 data members, a private header file will also be created, called <base‐
126 name>-private.h (for the example above it would be gtk-new-button-pri‐
127 vate.h). The public header file is created to be human readable and to
128 be used as a reference to the object. The .c source file is not cre‐
129 ated as a human readable source and is littered with #line statements,
130 which make the compiler attempt to point you to the right line in your
131 .gob file in case of parsing errors. The output should not be edited
132 by hand, and you should only edit the .gob file.
133
136 To include some code directly in the output C file begin with ´%{´ on
137 an empty line and end the code with a ´%}´ on an empty line. These
138 sections will appear in the output files in the order they are given.
139 There are several other sections to which you can put code. You can
140 put it in the ´header´ section (which can be abbreviated ´h´) and it
141 will go into the public header file. You can also put it in the ´pri‐
142 vateheader´ section (abbreviated ´ph´) which will make the code go into
143 the private header file. Sometimes you want some code (other includes)
144 to appear before the extern "C" and the protecting define. To do this
145 you can put them into the ´headertop´ (or ´ht´) section. You may wish
146 to include code or comments in all the files, which you can do by
147 putting them into the ´all´ (or ´a´) section. Similarly, code you wish
148 to appear at the top of all files go in the ´alltop´ (or ´at´) section.
149 For example:
150 %alltop{
152 /* this will be on top of all output files */
153 %}
154 %headertop{
156 /* this will be on top of the public header */
157 %}
158 %privateheader{
160 /* this will go into the private header file */
161 %}
162 %h{
164 /* will be included in the header */
165 void somefunc(int i);
166 %}
167 %a{
169 /* will be included in all files */
170 %}
171 %{
173 /* will be included in the C file */
174 void somefunc(int i)
175 {
176 /* some code */
177 }
178 %}
179
183 Gob will automatically include the class header file at the top of the
184 .c source file. If you wish to include it somewhere else, put the
185 include into some %{ %} section above the class definition, and gob
186 will not include it automatically. This way you can avoid circular
187 includes and control where in the file do you want to include the
188 header.
189 If you made any data members private, gob will also create a source
191 file that will be called <basename>-private.h. Same rule as above
192 applies for this just as it does for the regular header file. If you
193 do explicitly include the regular header file, you should always
194 include this private header file below it. That is, if you use any
195 private data members. If you don´t, the private header file automati‐
196 cally includes the public header file, and thus the public header file
197 will be indirectly included at the very top of the file.
198
201 There can be only one class per input file. Defining a class is sort
202 of like in Java, you define the class and write inline code directly
203 into the class definition. To define a class you need to specify the
204 new object name and the name of the object from which it is derived
205 from, such as this "class <new type> from <parent type> { <class code>
206 }". For example:
207 class Gtk:New:Button from Gtk:Button {
209 <class code>
210 }
211 To make an abstract class (to pass G_TYPE_FLAG_ABSTRACT) add
214 ´(abstract)´ before the curly braces above. This works since version
215 2.0.13.
216
219 There are five types of data members. Three of them are normal data
220 members, one is class wide (global) in scope and one is a virtual one,
221 usually linked to a normal data member or a class wide data member.
222 The three normal data members are public, protected and private. Pub‐
223 lic and protected are basically just entries in the object structure,
224 while private has it´s own dynamically allocated private structure.
225 Protected members are always put after the public one in the structure
226 and are marked protected in the header file. There is only one identi‐
227 fier allowed per typename unlike in normal C. Example:
228 public int i;
230 private GtkWidget *h;
231 protected long k;
232 Public and protected data members are accessed normally as members of
235 the object struct. Example where ´i´ is as above a public data member:
236 object->i = 1;
238 The private data members are defined in a structure which is only
241 available inside the .c file, or by including a private header file.
242 You must access them using the structure _priv. Example where ´h´ is
243 the private data member (as in the above example):
244 object->_priv->h = NULL;
246 The _priv structure is defined in the <basename>-private.h. This file
248 is automatically included if you don´t include it yourself. You should
249 always explicitly include it in your .gob file if you explicitly also
250 include the main header file. The reason it is a separate header file
251 is that you can also include it in other places that need to access
252 this objects private data, such as if you have the majority of func‐
253 tionality of an object in a separate .c file. Or if a derived object
254 needs to access the protected methods.
255 In case you use the --no-private-header option, no private header file
257 is created and you can only access the _priv pointer below the class
258 definition in the .gob file.
259 Also note that this structure is dynamically allocated, and is freed in
261 the finalize handler. If you override the finalized handler, your code
262 will be run first and only then will the _priv structure be freed.
263 Classwide data members:
265 Sometimes you want a datamember to be shared by all objects. You then
267 need the "classwide" scope keyword. So for example the following adds
268 a global member foo:
269 classwide int foo;
271 To access the member you do the standard voodoo of getting the class
273 from the object and casting it to your class pointer. Thus the follow‐
274 ing would work:
275 SELF_CLASS(GTK_OBJECT(object)->klass)->foo = 20;
277 Automatic Initialization:
280 You can automatically initialize the public private and protected data
282 members without having to add an init method. The advantage here is
283 that initialization is kept close to the definition of the data member
284 and thus it´s easier to check. To do this, just add a ´=´ followed by
285 a number or a token. It is also possible to include arbitrary C code
286 for more elaborate initializations by putting it all in curly braces.
287 Note that the curly braces will not be printed into the output, but
288 since gob does not C parsing it needs them to figure out where the C
289 code ends. The code will be inserted into the init method, above the
290 user defined body. So for example the following will initialize an
291 integer to -1 and a string with a newly allocated string of "hello".
292 public int foo = -1;
294 private char *bar = {g_strdup("hello")};
295 Automatic Destruction:
298 Most data stored as pointers needs to have a function called when the
300 object is finalized to either free the data. Gob will let you define a
301 function to be called on the data the object is finalized. This is
302 achieved by putting ´destroywith´ followed by a function name after the
303 variable definition. It is only called if the data you defined this on
304 is not NULL, so you cans specify functions which do not handle NULL.
305 It is very much like the GDestroyNotify function used in GTK+ and glib
306 in many places. Unlike many other places, gob will not enforce any
307 kind of type safety here so be a little bit more careful. Any function
308 you give it will be called as a "void function(void *)". It will in
309 fact be cast into such a form before called. This is to avoid spurious
310 warnings for gtk calls to subclass methods. The function needs not be
311 of that form exactly, it just has to take one argument which is the
312 pointer to the data. You should also not define this on any non-
313 pointer data as the results may be undefined. Example:
314 public char *foo = {g_strdup("bar")}
316 destroywith g_free;
317 Note that the function name you give must be a real function and not
319 macro. Also note that this is always called in the "finalize" method
320 of GObject. It is always called after any user defined body of the
321 finalize handler.
322 Sometimes you may want to run arbitrary code on destruction. While
324 this can be perfectly well done in the finalize handler. Depending on
325 the style you may want to include all destruction/initialization code
326 together with the definition of the data member. Thus you may want to
327 put arbitrary code which will then be inserted into the "finalize"
328 method of GObject. This can be done with the "destroy" keyword fol‐
329 lowed by arbitrary code in curly braces. Inside this code a macro
330 called VAR will be define which refers to your variable. So for exam‐
331 ple destroying a GString can be either done with a helper routine or
332 the following code:
333 public GString *string = {g_string_new(NULL)}
335 destroy {
336 if(VAR) g_string_free(VAR, TRUE);
337 };
338 The thing to remember with these is that there are many ways to do this
340 and you´d better be consistent in your code in how you use the above
341 things. Also defining a helper routine that will do the destruction
342 will be a nicer thing to do if that´s a possibility. The "destroy"
343 keyword with code does take up more space in the file and it may become
344 more cluttered.
345 The data is zeroed out after being destroyed. This is to make debug‐
347 ging easier in case your code might try to access an already finalized
348 object. In case you have overridden the finalize method, your code
349 will be run first and only then will the destructors be called. You
350 should not however make any assumptions about the order at which the
351 destructors are called. If you have interdependencies between destruc‐
352 tors for different data members, you will have to do this in your own
353 finalize override function.
354 Automatic Unreffing:
356 This is very much like the automatic destruction, but is instead run in
358 the dispose method (it is among other places called from the "destroy"
359 method of GtkObject). All data and other objects that you need to
360 unref should be done here, and not at finalize time. The semantics are
361 otherwise the same as for the "destroywith" and "destroy" keywords,
362 except that you use "unrefwith" and "unref".
363 public G:Object *foo = NULL
365 unrefwith g_object_unref;
366 public G:Object *bar = NULL
367 unref {
368 g_object_unref (VAR);
369 };
370
374 The fourth type of a data member a property type. It is a named data
375 member which is one of the features of the GObject system. It just
376 defines a way to get and set some data, but you have to take care of
377 storing that data somewhere. So it is normal to also have a normal
378 private (or public) data member where you store the real data. You
379 normally need to define a get and a set handler. They are fragments of
380 C code that will be used to get the value or set the value of the argu‐
381 ment. Inside them you can use the define VAL to which you assign the
382 data or get the data. You should treat this VAL as a GValue which
383 stores the data of the correct type. You can also use the identifier
384 "self" as pointer to the object instance. The type is defined as one
385 of the GObject type enums, but without the G_TYPE_ prefix. There are
386 also some attributes of a property which you can set. For example the
387 following is a definition of an integer property ´height´ which will be
388 synchronized with a private integer data member also of the name
389 ´height´.
390 private int height;
392 property INT height
393 (nick = _("Short nickname"),
394 blurb = _("Long description"),
395 minimum = 10,
396 maximum = 200,
397 default_value = 100)
398 set { self->_priv->height = g_value_get_int (VAL); }
399 get { g_value_set_int (VAL, self->_priv->height); };
400 The attributes are really optional though you should at least set some
403 of them. All property types have a ´nick´ and a ´blurb´ attribute and
404 you should set those accordingly. This will make runtime querying the
405 object nicer as things such as gui editors and class browsers can be
406 more verbose about the class itself. You can use the ´_("string")´
407 notation instead of just "string", and that will mark the string for
408 translation.
409 Almost all types also have a ´default_value´ attribute which sets the
411 initial value of this property (on object initialization, the set han‐
412 dler will be run automatically with this value). This value will be
413 overriden if the user sets a value of this property on the call to
414 g_object_new.
415 All the numeric types (including CHAR) have ´minimum´ and ´maximum´
417 attributes which can restrict the range. If you do not specify these
418 the range will be the full range that the data type can handle.
419 Types such as UNICHAR and BOOLEAN only have the ´nick´, ´blurb´ and
421 ´default_value´ attributes.
422 The ENUM type has an ´enum_type´ attribute which is the exact type of
424 the enum. This is so that the property knows which exact type you can
425 set, rather then just knowing it is an enum. You should always create
426 an enum type specific for the enum itself (see section on the enum
427 types)
428 Similarly FLAGS type has a ´flags_type´ which again you should set to
430 the specific type of this flags data member.
431 There is a STRING type which has only the extra ´default_value´
433 attribute.
434 The OBJECT type is one of the types that doesn´t have a ´default_value´
436 and it only has an ´object_type´ attribute (in addition to nick and
437 blurb of course) that is the exact object type that this property
438 accepts. The object_type should be as a type, that is for example
439 ´Gtk:Button´.
440 There is a BOXED type which is a pointer which has a boxed type defined
442 (such that GObject knows how to copy and destroy this pointer). Here
443 you will need to specify the ´boxed_type´ attribute with the specific
444 type of the boxed pointer.
445 There is also a POINTER type, which has only the ´nick´ and ´blurb´
447 attributes. This is for storing arbitrary pointers. You should be
448 careful with this one, as GObject knows nothing about the data stored
449 at this pointer. It is somewhat like a ´void *´ type.
450 There is also the PARAM type for storing parameters with a ´param_type´
452 attribute.
453 You should notice that this list is pretty much like the list of
455 g_param_spec_* functions from gobject/gparamspecs.h, and the attributes
456 are like the arguments of those functions. Note however that value
457 array is NOT supported yet.
458 You can also specify extra flags, such as CONSTRUCT or CONSTRUCT_ONLY
460 using the ´flags´ attribute. You can specify multiple flags by oring
461 them together with ´|´. These flags correspond to the GParamFlags enu‐
462 meration except do not include the G_PARAM_ prefix. So for example to
463 define an enumeration property, which is a CONSTRUCT_ONLY property, we
464 could do the following:
465 private SomeEnumerationType foo;
467 property ENUM foo
468 (nick = _("Short nickname"),
469 blurb = _("Long description"),
470 enum_type = Some:Enumeration:Type
471 default_value = SOME_ENUMERATION_VALUE,
472 flags = CONSTRUCT_ONLY,
473 link);
474 The above example also gives an example of automatic linking to a stan‐
477 dard data memember. By including the attribute ´link´ a get and set
478 handlers will be automatically added without having to type them by
479 hand. This is useful for a vast majority data types that are just
480 linked to some standard data member and do not need to do anything
481 extra on get or set.
482 Another extra feature of properties is the possibility of automatically
484 exporing methods to get and set the property. That is without having
485 to use g_object_set and g_object_get. This is achieved by adding an
486 ´export´ attribute to the list of property attributes.
487 If you do not define a set or get handler, the property will automati‐
489 cally be only readable or writable as appropriate.
490 Gob2 also creates macros which can be used for type safe access to
492 properties through g_object_set and g_object_get. The macros are
493 called <type>_PROP_<argument name>(x) and <type>_GET_PROP_<argument
494 name>(x). They define both the string and the value part of the argu‐
495 ment. So for setting an argument of height, one would use (for object
496 type My:Object):
497 g_object_set (G_OBJECT (object),
499 MY_OBJECT_PROP_HEIGHT (7),
500 NULL);
501 And for getting, you would use:
503 int height;
505 g_object_get (G_OBJECT (object),
506 MY_OBJECT_GET_PROP_HEIGHT (&height),
507 NULL);
508 Note however that the type safety only works completely on GNU C com‐
510 pilers. The code will compile on other compilers but with minimal type
511 safety. For complete type safety it is useful to use the get/set meth‐
512 ods that are defined by using the ´export´ attribute.
513 To get bettery type safety on some of the property types, you can spec‐
515 ify the ´type´ attribute which will add casts where appropriate in code
516 dealing with this property. This is especially useful for POINTER and
517 OBJECT types. But even for others.
518 You can also override properties from parent objects (that is override
520 their implementation, not their attributes). Do this by adding the
521 special ´override´ attribute. For example if the parent object had a
522 ´height´ property then you could override it by
523 private int height;
525 property INT height
526 (override)
527 set { self->_priv->height = g_value_get_int (VAL); }
528 get { g_value_set_int (VAL, self->_priv->height); };
529 Overriding is supported since gob 2.0.10.
531
534 There is a whole array of possible methods. The three normal, "famil‐
535 iar" method types are private, protected and public. Public are
536 defined as normal functions with a prototype in the header file. Pro‐
537 tected methods are defined as normal methods (which you can call from
538 other files), but their prototype is placed in the private header file.
539 Private methods are defined as static functions with prototypes at the
540 top of the .c file. Then there are signal, virtual and override meth‐
541 ods. More on those later. You can also define init and class_init
542 methods with a special definition if you want to add code to the con‐
543 structors or you can just leave them out. You can also not define a
544 body for a method, by just using ´;´ instead of a body. This will
545 define an empty function. You can´t do this for non-void regular pub‐
546 lic, private or protected methods, however it is acceptable for non-
547 void virtual, signal and override methods.
548 Function argument lists:
550 For all but the init and class_init methods, you use the following syn‐
552 tax for arguments. The first argument can be just "self", which gob
553 will translate into a pointer to the object instance. The rest of the
554 arguments are very similar to normal C arguments. If the typename is
555 an object pointer you should use the syntax defined above with the
556 words separated by ´:´
557 <type> <argument id>
558 or
559 <type> <argument id> (check <list of checks>)
560 The checks are glib type preconditions, and can be the following:
562 "null", which tests pointers for being NULL, "type" which checks GTK+
563 object pointers for being the right type, "<test> <number>" which tests
564 numeric arguments for being a certain value. The test can be a
565 <,>,<=,>= != or ==. Example:
566 public int
568 foo (self,
569 int h (check > 0 < 11),
570 Gtk:Widget *w (check null type))
571 This will be the prototype of a function which has a self pointer as
574 the first argument, an integer argument which will be checked and has
575 to be more then 0 and less then 11, and a pointer to a GtkWidget object
576 instance and it is checked for being null and the type will also be
577 checked.
578 Error return:
580 Methods which have a return value, there also has to be something
582 returned if there is an error, such as if a precondition is not met.
583 The default is 0, casted to the type of the method. If you need to
584 return something else then you can specify an "onerror" keyword after
585 the prototype and after that a number, a token (an identifier) or a bit
586 of C code enclosed in braces {}. The braces will not be printed into
587 the output, they just delimit the string. For example:
588 public void * get_something (self, int i (check >= 0)) onerror NULL {
590 ...
591 }
592 The onerror value is also used in overrides that have a return value,
594 in case there isn´t a parent method, PARENT_HANDLER will return it.
595 More about this later.
596 Default return:
598 Some signal and virtual methods have a return type. But what happens
600 if there is no default handler and no one connects to a signal. GOB2
601 will normally have the wrappers return whatever you specify with
602 onerror or ´0´ if you haven´t specified anything. You can also specify
603 a default return value with the keyword ´defreturn´. It´s use is iden‐
604 tical to the use of onerror, and you can in fact use both at the same
605 time. Example
606 virtual int get_some_int (self) onerror -1 defreturn 10 ;
608 That is an empty virtual method (in C++ terms a pure virtual). If you
610 never specify any handler for it in the derived children it will just
611 return 10.
612 Constructor methods:
614 There are two methods that handle the construction of an object, init
616 and class_init. You define them by just using the init or class_init
617 keyword with an untyped argument in the argument list. The argument
618 will be usable in your function as a pointer to your object or class
619 depending if it´s init or class_init. For example:
620 init (self) {
622 /* initialize the object here */
623 self->a = 9;
624 self->b = 9;
625 }
626 class_init (class) {
628 /* initialize the class, this is rarely needed */
629 class->blah = NULL;
630 }
631 The class_init function is very rarely needed as all standard class
633 initialization is taken care of for you by gob itself. The init func‐
634 tion should on the other hand be used whenever you need to construct or
635 initialize anything in the object to put it into a sane state.
636 Virtual methods:
638 Virtual methods are basically pointers in the class structure, so that
640 one can override the method in derived methods. That is to implement
641 the method in a derived class, you must then use an override method
642 (more on those later). They can be empty (if you put ´;´ instead of
643 the C code). A wrapper will also be defined which makes calling the
644 methods he same as public methods. This type of method is just a lit‐
645 tle bit "slower" then normal functions, but not as slow as signals.
646 You define them by using "virtual" keyword before the prototype. If
647 you put the keyword "private" right after the "virtual" keyword, the
648 wrapper will not be a public method, but a private one. You can do the
649 same with "protected" to make a protected wrapper.
650 Signals:
652 Signals are methods to which the user can bind other handlers and over‐
654 ride the default handler. The default handler is basically the method
655 body. This is the most versatile and flexible type of a method and
656 also the slowest. You need to specify a whole bunch of things when you
657 define a signal. One thing is when the default handler will be run,
658 first or last. You specify that by "first" or "last" right after the
659 "signal" keyword. Then you need to define the GObject enum types
660 (again without the G_TYPE_ prefix). For that you define the return
661 types and the types of arguments after the "self" pointer (not includ‐
662 ing the "self" pointer). You put it in the following syntax "<return
663 type> (<list of arguments>)". If the return type is void, the type
664 should be "NONE", the same should be for the argument list. The rest
665 of the prototype is the same as for other method types. The body can
666 also be empty, and also there is a public method wrapper which you can
667 use for calling the signal just like a public method. Example:
668 signal first INT (POINTER, INT)
670 int do_something (self, Gtk:Widget *w (check null type), int length)
671 {
672 ...
673 }
674 or
676 signal last NONE (NONE) void foo (self);
678 If you don´t want the wrapper that emits the signal to be public, you
681 can include the keyword "private" after the "signal" keyword. This
682 will make the wrapper a normal private method. You can also make a
683 protected wrapper by using "protected" instead of "private".
684 If you don´t define a "first" or a "last", the default will be taken as
686 "last".
687 You can also add additional flags. You do this just like with the
689 argument flags, although this is probably very rare. These are the
690 G_SIGNAL_* flags, and you can add them without the G_SIGNAL_ prefix
691 into a parenthesis, just after the "signal" keyword. By default all
692 public signals are G_SIGNAL_ACTION.
693 Also gob2 creates a wrapper macros for typesafe signal connection.
695 That is you will be warned by the compiler if you pass a callback that
696 is not the correct prototype. This will again only warn you on gcc,
697 but it will compile without warning on another compiler. So as with
698 all the typesafety hacks in gob, it is better to test your objects
699 under gcc to get any warnings even if you are using a different com‐
700 piler in the end.
701 The methods that are created for you are:
703 <class_name>_connect__<signal_name> (<object>, <callback>, <data>)
705 <class_name>_connect_after__<signal_name> (<object>, <callback>, <data>)
706 <class_name>_connect_data__<signal_name> (<object>, <callback>, <data>,
707 <destroy_notify>, <flags>)
708 These three functions correspond to the g_signal_connect, g_signal_con‐
711 nect_after and g_signal_connect_data functions that you would normally
712 use, except they are for a specific signal. Also do note the two
713 underscores between the method name and the signal name. For example
714 to connect the signal "foo" on the object "Test:Object" you would do:
715 test_object_connect__foo (object, callback, data);
717 To use BOXED in the signal arguments you need to tell gob which type of
720 boxed argument you want to use. For this you can just add
721 BOXED_GTK_TYPE_STRING instead of BOXED. For example
722 BOXED_GTK_TYPE_TREE_ITER for GtkTreeIter. This works since version
723 2.0.13.
724 Override methods:
726 If you need to override some method (a signal or a virtual method of
728 some class in the parent tree of the new object), you can define and
729 override method. After the "override" keyword, you should put the
730 typename of the class you are overriding a method from. Other then
731 that it is the same as for other methods. The "self" pointer in this
732 case should be the type of the method you are overriding so that you
733 don´t get warnings during compilation. Also to call the method of the
734 parent class, you can use the PARENT_HANDLER macro with your arguments.
735 Example:
736 override (Gtk:Container) void
738 add (Gtk:Container *self (check null type), Gtk:Widget *wid (check null type))
739 {
740 /* some code here */
741 PARENT_HANDLER(self, wid);
742 }
743 If the function has a return value, then PARENT_HANDLER is an expres‐
745 sion that you can use. It will return whatever the parent handler
746 returned, or the "onerror" expression if there was no parent handler.
747 Method names:
749 Inside the code, aliases are set for the methods, so that you don´t
751 have to type the class name before each call, just type self_ instead
752 of the name of the class. So to call a method called blah, you would
753 use the name self_blah. Example:
754 private int
756 foo (self)
757 {
758 return self->len;
759 }
760 private int
762 bar (self, int i)
763 {
764 return self_foo (self) + i;
765 }
766
770 You should define a new method which should be a normal public method.
771 Inside this method, you can use the GET_NEW macro that is defined for
772 you and that will fetch a new object, so a fairly standard new method
773 would look like:
774 public GObject *
776 new (void) {
777 GObject *ret = GET_NEW;
778 return G_OBJECT (ret);
779 }
780 You should not a subtle peculiarity of the GObject system here. If
783 there is any code inside the G_OBJECT macro argument, it will get exe‐
784 cuted multiple times. This means that things such as G_OBJECT(GET_NEW)
785 would actually create 4 objects, leaking 3 of them. A good rule (as
786 with anywhere in C) is to be careful with all macros.
787
790 Self alias casts:
791 There are some standard casts defined for you. Instead of using the
793 full macros inside the .c file, you can use SELF, IS_SELF and
794 SELF_CLASS. Using these makes it easier to for example change class
795 names around.
796 Self alias types:
798 There are also the Self and SelfClass types inside your .c file. These
800 serve the same function as the above, they make it easier to type and
801 easier to change typenames around which can help a lot during prototyp‐
802 ing stage. However you should note that the Self type should not be
803 used in function prototypes as one of the arguments or as a return
804 value type. This is because this is a simple C typedef which is only
805 available inside your .c file and not in the header files. You can
806 disable both the self casting macros and the self type aliases by pass‐
807 ing --no-self-alias to gob.
808
811 Defines:
812 In your generated C file, you can use the defines GOB_VERSION_MAJOR
814 GOB_VERSION_MINOR and GOB_VERSION_PATCHLEVEL if you wish to for example
815 use a feature that is only available in some newer gob version. Note
816 however that you can only use these defines in the C code portions of
817 your .gob file, and #ifdef´s cannot span multiple functions. Check the
818 BUGS section for more on using the C preprocessor and gob.
819 Minimum version requires:
821 You can also make your .gob file require at least certain version of
823 gob. You do this by putting ´requires x.y.z´ (where x.y.z is the ver‐
824 sion number) outside of any C block, comment or class, usually you
825 should make this the first line in the file or close to the top. If
826 gob finds this and the version of gob used to compile the code is lower
827 then that listed in the require, gob will generate an error and exit.
828 For example to require that gob2 version 2.0.0 or higher be used to
829 compile a file, put this at the top of that file:
830 requires 2.0.0
832
836 You can create new GObject ENUM, FLAGS and GError types for use in your
837 classes easily. Glib includes some utilities for handling these, how‐
838 ever it may be cleaner to use the below specified way in your classes.
839 It also then doesn´t require any Makefile setup. Make sure this is
840 defined in the same section as the class, that is not in any of the
841 ´%?{´ ´%}´ sections.
842 You use the keywords ´enum´ ´flags´ and ´error´ as you would use the
844 ´class´ keyword. Then you give a prefix for the values in the enumera‐
845 tion. Then you define a list of values just like in C. For ´enum´
846 types you can also specify the values assigned to each string. Then
847 you specify the type in the standard gob style of specifying types.
848 Here are a few examples of all of these:
849 enum LAME_CLIENT {
851 IS_CONNECTED,
852 NONE = 9,
853 LAST
854 } Test:Enum;
855 flags BUGA_BUGA {
857 ONE,
858 TWO,
859 MANY,
860 } Some:Flags;
861 error TEST_OBJECT_ERROR {
863 BAD_THIS,
864 BAD_THAT
865 } Test:Object:Error;
866 This will for example define an enum that is equivalent to the follow‐
869 ing C code:
870 typedef enum {
872 LAME_CLIENT_IS_CONNECTED,
873 LAME_CLIENT_NONE = 9,
874 LAME_CLIENT_LAST
875 } TestEnum;
876
880 There is a C++ mode so that gob creates C++ compiler friendly files.
881 You need to use the --for-cpp argument to gob. This will make the gen‐
882 erated file have a .cc instead of a .c extension, and several things
883 will be adjusted to make it all work for a C++ compiler. One thing
884 that will be missing is an alias to the new method, as that clashes
885 with C++, so instead you´ll have to use the full name of the method
886 inside your code. Also note that gob does not use any C++ features,
887 this option will just make the generated code compile with a C++ com‐
888 piler.
889
892 The get_type is not really a method, but a function which initializes
893 your object. Recently objects appeared which require you to make a
894 custom get_type function. So it is possible to override this function.
895 To do so, just define a new public method called get_type, with no
896 arguments. Example:
897 public GType
899 get_type (void)
900 {
901 /* code goes here */
902 return some_type;
903 }
904
908 Currently gob will only allow you to implement interfaces (that is,
909 define new classes which implement an interface) and doesn´t yet have
910 support for making new interfaces, but this will be coming at some
911 point in the future.
912 To define a class that implements an interface add a class flag ´inter‐
914 face´ with the type name of the interface as an argument. Then to
915 implement a specific method of the interface, just add ´interface
916 <typename>´ before the method definition. The method can, and probably
917 should be, private.
918 The following example implements a new object, that implements the
920 Gtk:Tree:Model interface and implements the get_flags method of that
921 interface. Do note that except for standard (GTK+ and glib) specific
922 interfaces which seem to have a non-standard name for the interface
923 structure, the structure should end with and Iface, if you are imple‐
924 menting an interface. That is for example for the Gtk:Tree:Model, the
925 structure containing the table of methods should be named GtkTreeMod‐
926 elIface.
927 class Some:Object from G:Object
928 (interface Gtk:Tree:Model)
929 {
930 /* function implemented for the Gtk:Tree:Model interface */
931 interface Gtk:Tree:Model
932 private GtkTreeModelFlags
933 get_flags (Gtk:Tree:Model *self (check null type))
934 {
935 /* Here would be the implementation */
936 return (GtkTreeModelFlags)0;
937 }
938 }
939 If you want to implement multiple interfaces just list more class flag
942 lines as follows:
943 class Some:Object from G:Object
945 (interface Gtk:Tree:Model)
946 (interface Gtk:Editable)
947 {
948 /* ... */
949 }
950
954 If you want to build a BonoboObject class gob2 has direct support for
955 these. Just create a new object that derives from Bonobo:Object. Then
956 use a "BonoboObject" class flag with the interface name as an argument.
957 The interface name should be as you would type it in C, that is with
958 underscores as namespace separators. Then you add the methods (using
959 exact same names as in the idl file) and prepend those methods with a
960 BonoboObject keyword. For example imagine you have an interface
961 GNOME/Foo/SomeInterface, with a method fooBar that takes a single
962 string:
963 class Foo:Some:Interface from Bonobo:Object
965 (BonoboObject GNOME_Foo_SomeInterface) {
966 BonoboObject
968 private void
969 fooBar (PortableServer_Servant servant,
970 const CORBA_char *string,
971 CORBA_Environment *ev)
972 {
973 Self *self = SELF (bonobo_object_from_servant (servant));
974 /* your code here */
976 }
977 /* rest of class */
979 }
980 Note that the implementation method can be private, in fact that´s
982 probably a good idea to do. It won´t work to make this a signal, it
983 can however be a virtual. Note that the method prototype must match
984 the one from the interface header file, or you will get a bad assign‐
985 ment warning. You should check the header file generated by orbit-idl
986 and see the epv structure for the correct prototypes if you can´t fig‐
987 ure them out from the idl itself. Also note that the first argument is
988 not "self", but the servant and you must use bonobo_object_from_servant
989 function to get the actual object pointer.
990
993 Gob can simplify writing a libglade class. Just create a new object
994 that derives from a GtkContainer widget. Then use a "GladeXML" class
995 flag with the glade file name, root widget and optional domain as
996 arguments between double quotes. For example:
997 class My:Glade from Gtk:Window (GladeXML "gob-libglade.glade" "root")
999 {
1000 ....
1001 }
1002 Note however that then "gob-libglade.glade" would have to be in the
1004 current directory. You could specify a path, but that may not work for
1005 all installations. You can replace the glade filename with a token to
1006 be used in the generated .c file and you can then have a macro with the
1007 filename, as follows:
1008 class My:Glade from Gtk:Window (GladeXML GLADE_FILE "root")
1010 {
1011 ....
1012 }
1013 And somewhere in your header files you would have
1015 #define GLADE_FILE "/path/to/file.glade"
1017 You can declare widgets as data members by adding a 'GladeXML' to the
1020 definition.
1021 private Gtk:Button * button1 GladeXML;
1023 This will automatically set the "button1" from the GladeXML file.
1025 All signals created with glade are automatically connected if you
1027 defined those class methods in your class. For example suppose in
1028 glade that we set the "connect" signal on button1 to go to on_but‐
1029 ton1_clicked, then in our gob file we can just write:
1030 public void
1032 on_button1_clicked(self, GtkButton * button)
1033 {
1034 }
1035 See the examples directory for a full example. Note that this feature
1038 requires version at least 2.0.12.
1039
1043 Gob will need to define some local variables and functions in the gen‐
1044 erated files, so you need to take some precaution not to conflict with
1045 these. The general rule of thumb is that all of these start with three
1046 underscores. There is one, "parent_class" which doesn´t because it´s
1047 intended for use in your code. For virtuals or signals, you cannot use
1048 the identifier __parent__ which is used for the parent of the object.
1049 You should actually never access __parent__ either as it not guaranteed
1050 that it will stay named this way. Data members cannot be named __par‐
1051 ent__ nor _priv. For methods, you cannot use the identifiers "init" or
1052 "class_init" unless you mean the constructor methods. You shouldn´t
1053 generally use 3 underscores even in override method argument lists and
1054 virtual and signal method names as it might confuse the PARENT_HANDLER
1055 macro. In fact avoiding all names with three underscores is the best
1056 policy when working with gob.
1057 There are a couple of defines which you shouldn´t be redefining in the
1059 code or other headers. These are SELF, IS_SELF, SELF_CLASS, SELF_TYPE,
1060 ARG, VAR, PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR
1061 and GOB_VERSION_PATCHLEVEL.
1062 As for types, there are Self and SelfClass types which are only defined
1064 in your source files. Their generation (just like the generation of
1065 the SELF macros) can be turned off, see command line options.
1066
1069 If you want to use gtk-doc style inline documentation for your objects,
1070 you can do one of two things. First, you could include the inline doc‐
1071 umentation comments in your %{ %} section which will then be put verba‐
1072 tim into the output source file. This is the way you should use for
1073 functions you define outside of the class.
1074 For class methods, you should use a gtk+ style comment, however it can
1076 be indented any number of tabs or spaces and you can use the short
1077 method name without the type prefix. Gob will automatically try to
1078 extract these and translate to full names and put them in the output
1079 source file. An example would be:
1080 class Gtk:Button:Example from Gtk:Button {
1082 /**
1083 * new:
1084 *
1085 * Makes a new #GtkButtonExample widget
1086 *
1087 * Returns: a new widget
1088 **/
1089 public
1090 GtkWidget *
1091 new(void)
1092 {
1093 return (GtkWidget *)GET_NEW;
1094 }
1095 }
1096 If the function you are documenting is a signal or a virtual then it
1098 will be documenting the wrapper that starts that virtual function or
1099 emits that signal.
1100
1103 Sometimes you may need to use an object of type MyObjectA in the MyOb‐
1104 jectB class and vice versa. Obviously you can´t include headers for
1105 both. So you need to just declare the typedef in the header of A for
1106 B, and the other way around as well. The headers generated include a
1107 protecting define before it declares the typedef. This define is the
1108 __TYPEDEF_<upper case object name>__. So inside my-object-a.h there
1109 will be this:
1110 #ifndef __TYPEDEF_MY_OBJECT_A__
1112 #define __TYPEDEF_MY_OBJECT_A__
1113 typedef struct _MyObjectA MyObjectA;
1114 #endif
1115 Now instead of including my-object-a.h in the header section of my-
1117 object-b.gob, just copy the above code there and you´re set for using
1118 MyObjectA as a type in the method parameters and public types.
1119 Another way to get out of this problem is if you can use those types
1121 only in the private members, in which case they won´t be in the gener‐
1122 ated public header.
1123
1126 If you are using normal makefiles, what you need to do is to add a
1127 generic rule for .gob files. So you would include the following in the
1128 Makefile and then just use the .c and .h files as usual (make sure the
1129 space before the ´gob2´ is a tab, not spaces):
1130 %.c %.h %-private.h: %.gob
1132 gob2 $<
1133
1137 This is a little bit more involved. Basically the first thing to do is
1138 to check for GOB2 in your configure.in file. You can use the supplied
1139 m4 macro which will also check the version of gob. Basically you
1140 include this:
1141 GOB2_CHECK([2.0.0])
1143 This will replace @GOB2@ in your makefiles with the full path of gob2.
1145 Thus when adding the generic rule to your Makefile.am file, it should
1146 look like:
1147 %.c %.h %-private.h: %.gob
1149 @GOB2@ $<
1150 For Makefile.am you have to set up a couple more things. First you
1153 have to include the generated .c and .h files into BUILT_SOURCES vari‐
1154 able. You have to include both the .gob and the .c and .h files in the
1155 SOURCES for your program.
1156
1159 When nothing has changed you might not really want to rebuild every‐
1160 thing and gob provides options --no-touch (since 2.0.13) and --no-
1161 touch-headers to avoid this. When working with build systems such as
1162 automake you have to be more careful as just using those options can
1163 cause automake to get confused and you will need to use something like
1164 the following:
1165 foo_SOURCES = foo.gob foo.gob.stamp foo.c foo.h foo-private.h
1167 BUILT_SOURCES = foo.gob.stamp
1168 MAINTAINERCLEANFILES = foo.gob.stamp
1169 %.gob.stamp: %.gob
1171 @GOB2@ --no-touch $<
1172 @touch $@
1173
1177 GOB does several things to make debugging the code easier. First it
1178 adds preprocessor commands into the output c file that point to the
1179 correct places in your .gob input file. However sometimes there might
1180 be some bigger confusion and this is just not helpful. In this case
1181 you will probably want to have gcc point you directly at the generated
1182 files. For this use the --no-lines command line option. You should
1183 also note that these commands are not generated for the public header
1184 file at all. If there is an error which points you to the public
1185 header file, make sure you fix this error in the .gob file, otherwise
1186 your changes will not have any effect after gob recompiles the sources
1187 again.
1188 Sometimes you might want to know which method you are in for some
1190 debugging output. GOB will define __GOB_FUNCTION__ macro, which is
1191 just a string constant with a pretty name of the method.
1192
1195 It is possible to have your .gob file also preprocessed by m4. This is
1196 useful if you have a lot of files and you´d like to have some pre‐
1197 processor put in some common features. All you have to do is add --m4
1198 to the command line of gob2 and gob2 will first run your file through
1199 m4. You can print the directory that is searched for m4 files by run‐
1200 ning "gob2 --m4-dir"
1201 All the arguments after --m4 will be passed to m4 itself, so it has to
1203 be the last gob2 argument on the command line. This way you can spec‐
1204 ify arbitrary options to pass to m4.
1205
1208 The lexer does not actually parse the C code, so I´m sure that some
1209 corner cases or maybe even some not so corner cases of C syntax might
1210 confuse gob completely. If you find any, send me the source that makes
1211 it go gaga and I´ll try to make the lexer try to handle it properly,
1212 but no promises.
1213 Another thing is that gob ignores preprocessor macros. Since gob
1215 counts braces, the following code won´t work:
1216 #ifdef SOME_DEFINE
1218 if(foo) {
1219 #else
1220 if(bar) {
1221 #endif
1222 blah();
1223 }
1224 To make this work, you´d have to do this:
1226 #ifdef SOME_DEFINE
1228 if(foo)
1229 #else
1230 if(bar)
1231 #endif
1232 {
1233 blah();
1234 }
1235 There is no real good way we can handle this without parsing C code, so
1237 we probably never will. In the future, I might add #if 0 as a comment
1238 but that´s about as far as I can really take it and even that is prob‐
1239 lematic. Basically, if you use gob, just don´t use the C preprocessor
1240 too extensively. And if you use it make sure that you do not cross the
1241 boundaries of the C code segments.
1242 Comments will not get through to the generated files unless inside C
1244 code. This is not the case for gtk-doc style comments which are sup‐
1245 ported.
1246 The short name aliases are actually implemented as pointers to func‐
1248 tions. Thus if you want to get the pointer of a function using the
1249 short name alias you can´t use the ´&´. Thus:
1250 void (*foo)(Self *);
1252 /* this will NOT work */
1254 foo = &self_short_name;
1255 /* this will work */
1257 foo = self_short_name;
1258 /* Both of these will work */
1260 foo = &my_class_long_name;
1261 foo = my_class_long_name;
1262
1266 George Lebl <jirka@5z.com>
1267 GOB2 Homepage: http://www.jirka.org/gob.html
1269 GOB2 2.0.14 GOB2(1)