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 When you want code to appear as in alltop but only in the cfile you use
150 the ´ctop´ (or ´ct´) section. Note that ctop requires 2.0.18.
151 Finally, ´afterdecls´ includes code between the declarations and the
152 method implementations, but note that ´afterdecls´ requires version
153 2.0.16. For example:
154 %alltop{
156 /* this will be at the very top of all output files */
157 %}
158 %ctop{
160 /* this will be at the very top of the C file */
161 /* Requires 2.0.18 */
162 %}
163 %headertop{
165 /* this will be on top of the public header */
166 %}
167 %privateheader{
169 /* this will go into the private header file */
170 %}
171 %h{
173 /* will be included in the header */
174 void somefunc(int i);
175 %}
176 %a{
178 /* will be included in all files */
179 %}
180 %afterdecls{
182 /* between the declarations and the method implementations */
183 /* Requires gob version 2.0.16 */
184 %}
185 %{
187 /* will be included in the C file */
188 void somefunc(int i)
189 {
190 /* some code */
191 }
192 %}
193
197 Gob will automatically include the class header file at the top of the
198 .c source file. If you wish to include it somewhere else, put the
199 include into some %{ %} section above the class definition, and gob
200 will not include it automatically. This way you can avoid circular
201 includes and control where in the file do you want to include the
202 header.
203 If you made any data members private, gob will also create a source
205 file that will be called <basename>-private.h. Same rule as above
206 applies for this just as it does for the regular header file. If you
207 do explicitly include the regular header file, you should always
208 include this private header file below it. That is, if you use any
209 private data members. If you don´t, the private header file automati‐
210 cally includes the public header file, and thus the public header file
211 will be indirectly included at the very top of the file.
212
215 There can be only one class per input file. Defining a class is sort
216 of like in Java, you define the class and write inline code directly
217 into the class definition. To define a class you need to specify the
218 new object name and the name of the object from which it is derived
219 from, such as this "class <new type> from <parent type> { <class code>
220 }". For example:
221 class Gtk:New:Button from Gtk:Button {
223 <class code>
224 }
225 To make an abstract class (to pass G_TYPE_FLAG_ABSTRACT) add
228 ´(abstract)´ before the curly braces above. This works since version
229 2.0.13.
230
233 There are five types of data members. Three of them are normal data
234 members, one is class wide (global) in scope and one is a virtual one,
235 usually linked to a normal data member or a class wide data member.
236 The three normal data members are public, protected and private. Pub‐
237 lic and protected are basically just entries in the object structure,
238 while private has it´s own dynamically allocated private structure.
239 Protected members are always put after the public one in the structure
240 and are marked protected in the header file. There is only one identi‐
241 fier allowed per typename unlike in normal C. Example:
242 public int i;
244 private GtkWidget *h;
245 protected long k;
246 Public and protected data members are accessed normally as members of
249 the object struct. Example where ´i´ is as above a public data member:
250 object->i = 1;
252 The private data members are defined in a structure which is only
255 available inside the .c file, or by including a private header file.
256 You must access them using the structure _priv. Example where ´h´ is
257 the private data member (as in the above example):
258 object->_priv->h = NULL;
260 The _priv structure is defined in the <basename>-private.h. This file
262 is automatically included if you don´t include it yourself. You should
263 always explicitly include it in your .gob file if you explicitly also
264 include the main header file. The reason it is a separate header file
265 is that you can also include it in other places that need to access
266 this objects private data, such as if you have the majority of func‐
267 tionality of an object in a separate .c file. Or if a derived object
268 needs to access the protected methods.
269 In case you use the --no-private-header option, no private header file
271 is created and you can only access the _priv pointer below the class
272 definition in the .gob file.
273 Also note that this structure is dynamically allocated, and is freed in
275 the finalize handler. If you override the finalized handler, your code
276 will be run first and only then will the _priv structure be freed.
277 Classwide data members:
279 Sometimes you want a datamember to be shared by all objects. You then
281 need the "classwide" scope keyword. So for example the following adds
282 a global member foo:
283 classwide int foo;
285 To access the member you can use the SELF_GET_CLASS macro (or
287 YOUR_OBJECT_NAME_GET_CLASS) to get at the class. Thus the following
288 would work:
289 SELF_GET_CLASS(object)->foo = 20;
291 Automatic Initialization:
294 You can automatically initialize the public private and protected data
296 members without having to add an init method. The advantage here is
297 that initialization is kept close to the definition of the data member
298 and thus it´s easier to check. To do this, just add a ´=´ followed by
299 a number or a token. It is also possible to include arbitrary C code
300 for more elaborate initializations by putting it all in curly braces.
301 Note that the curly braces will not be printed into the output, but
302 since gob does not C parsing it needs them to figure out where the C
303 code ends. The code will be inserted into the init method, above the
304 user defined body. So for example the following will initialize an
305 integer to -1 and a string with a newly allocated string of "hello".
306 public int foo = -1;
308 private char *bar = {g_strdup("hello")};
309 Automatic Destruction:
312 Most data stored as pointers needs to have a function called when the
314 object is finalized to either free the data. Gob will let you define a
315 function to be called on the data the object is finalized. This is
316 achieved by putting ´destroywith´ followed by a function name after the
317 variable definition. It is only called if the data you defined this on
318 is not NULL, so you cans specify functions which do not handle NULL.
319 It is very much like the GDestroyNotify function used in GTK+ and glib
320 in many places. Unlike many other places, gob will not enforce any
321 kind of type safety here so be a little bit more careful. Any function
322 you give it will be called as a "void function(void *)". It will in
323 fact be cast into such a form before called. This is to avoid spurious
324 warnings for gtk calls to subclass methods. The function needs not be
325 of that form exactly, it just has to take one argument which is the
326 pointer to the data. You should also not define this on any non-
327 pointer data as the results may be undefined. Example:
328 public char *foo = {g_strdup("bar")}
330 destroywith g_free;
331 Note that the function name you give must be a real function and not
333 macro. Also note that this is always called in the "finalize" method
334 of GObject. It is always called after any user defined body of the
335 finalize handler.
336 Sometimes you may want to run arbitrary code on destruction. While
338 this can be perfectly well done in the finalize handler. Depending on
339 the style you may want to include all destruction/initialization code
340 together with the definition of the data member. Thus you may want to
341 put arbitrary code which will then be inserted into the "finalize"
342 method of GObject. This can be done with the "destroy" keyword fol‐
343 lowed by arbitrary code in curly braces. Inside this code a macro
344 called VAR will be define which refers to your variable. So for exam‐
345 ple destroying a GString can be either done with a helper routine or
346 the following code:
347 public GString *string = {g_string_new(NULL)}
349 destroy {
350 if(VAR) g_string_free(VAR, TRUE);
351 };
352 The thing to remember with these is that there are many ways to do this
354 and you´d better be consistent in your code in how you use the above
355 things. Also defining a helper routine that will do the destruction
356 will be a nicer thing to do if that´s a possibility. The "destroy"
357 keyword with code does take up more space in the file and it may become
358 more cluttered.
359 The data is zeroed out after being destroyed. This is to make debug‐
361 ging easier in case your code might try to access an already finalized
362 object. In case you have overridden the finalize method, your code
363 will be run first and only then will the destructors be called. You
364 should not however make any assumptions about the order at which the
365 destructors are called. If you have interdependencies between destruc‐
366 tors for different data members, you will have to do this in your own
367 finalize override function.
368 Automatic Unreffing:
370 This is very much like the automatic destruction, but is instead run in
372 the dispose method (it is among other places called from the "destroy"
373 method of GtkObject). All data and other objects that you need to
374 unref should be done here, and not at finalize time. The semantics are
375 otherwise the same as for the "destroywith" and "destroy" keywords,
376 except that you use "unrefwith" and "unref".
377 public G:Object *foo = NULL
379 unrefwith g_object_unref;
380 public G:Object *bar = NULL
381 unref {
382 g_object_unref (VAR);
383 };
384
388 The fourth type of a data member a property type. It is a named data
389 member which is one of the features of the GObject system. It just
390 defines a way to get and set some data, but you have to take care of
391 storing that data somewhere. So it is normal to also have a normal
392 private (or public) data member where you store the real data. You
393 normally need to define a get and a set handler. They are fragments of
394 C code that will be used to get the value or set the value of the argu‐
395 ment. Inside them you can use the define VAL to which you assign the
396 data or get the data. You should treat this VAL as a GValue which
397 stores the data of the correct type. You can also use the identifier
398 "self" as pointer to the object instance. The type is defined as one
399 of the GObject type enums, but without the G_TYPE_ prefix. There are
400 also some attributes of a property which you can set. For example the
401 following is a definition of an integer property ´height´ which will be
402 synchronized with a private integer data member also of the name
403 ´height´.
404 private int height;
406 property INT height
407 (nick = _("Short nickname"),
408 blurb = _("Long description"),
409 minimum = 10,
410 maximum = 200,
411 default_value = 100)
412 set { self->_priv->height = g_value_get_int (VAL); }
413 get { g_value_set_int (VAL, self->_priv->height); };
414 The attributes are really optional though you should at least set some
417 of them. All property types have a ´nick´ and a ´blurb´ attribute and
418 you should set those accordingly. This will make runtime querying the
419 object nicer as things such as gui editors and class browsers can be
420 more verbose about the class itself. You can use the ´_("string")´
421 notation instead of just "string", and that will mark the string for
422 translation.
423 Almost all types also have a ´default_value´ attribute which sets the
425 initial value of this property (on object initialization, the set han‐
426 dler will be run automatically with this value). This value will be
427 overridden if the user sets a value of this property on the call to
428 g_object_new.
429 All the numeric types (including CHAR) have ´minimum´ and ´maximum´
431 attributes which can restrict the range. If you do not specify these
432 the range will be the full range that the data type can handle.
433 Types such as UNICHAR and BOOLEAN only have the ´nick´, ´blurb´ and
435 ´default_value´ attributes.
436 The ENUM type has an ´enum_type´ attribute which is the exact type of
438 the enum. This is so that the property knows which exact type you can
439 set, rather then just knowing it is an enum. You should always create
440 an enum type specific for the enum itself (see section on the enum
441 types)
442 Similarly FLAGS type has a ´flags_type´ which again you should set to
444 the specific type of this flags data member.
445 There is a STRING type which has only the extra ´default_value´
447 attribute.
448 The OBJECT type is one of the types that doesn´t have a ´default_value´
450 and it only has an ´object_type´ attribute (in addition to nick and
451 blurb of course) that is the exact object type that this property
452 accepts. The object_type should be as a type, that is for example
453 ´Gtk:Button´.
454 There is a BOXED type which is a pointer which has a boxed type defined
456 (such that GObject knows how to copy and destroy this pointer). Here
457 you will need to specify the ´boxed_type´ attribute with the specific
458 type of the boxed pointer.
459 There is also a POINTER type, which has only the ´nick´ and ´blurb´
461 attributes. This is for storing arbitrary pointers. You should be
462 careful with this one, as GObject knows nothing about the data stored
463 at this pointer. It is somewhat like a ´void *´ type.
464 There is also the PARAM type for storing parameters with a ´param_type´
466 attribute.
467 You should notice that this list is pretty much like the list of
469 g_param_spec_* functions from gobject/gparamspecs.h, and the attributes
470 are like the arguments of those functions. Note however that value
471 array is NOT supported yet.
472 You can also specify extra flags, such as CONSTRUCT or CONSTRUCT_ONLY
474 using the ´flags´ attribute. You can specify multiple flags by oring
475 them together with ´|´. These flags correspond to the GParamFlags enu‐
476 meration except do not include the G_PARAM_ prefix. So for example to
477 define an enumeration property, which is a CONSTRUCT_ONLY property, we
478 could do the following:
479 private SomeEnumerationType foo;
481 property ENUM foo
482 (nick = _("Short nickname"),
483 blurb = _("Long description"),
484 enum_type = Some:Enumeration:Type
485 default_value = SOME_ENUMERATION_VALUE,
486 flags = CONSTRUCT_ONLY,
487 link);
488 The above example also gives an example of automatic linking to a stan‐
491 dard data memember. By including the attribute ´link´ a get and set
492 handlers will be automatically added without having to type them by
493 hand. This is useful for a vast majority data types that are just
494 linked to some standard data member and do not need to do anything
495 extra on get or set.
496 Another extra feature of properties is the possibility of automatically
498 exporing methods to get and set the property. That is without having
499 to use g_object_set and g_object_get. This is achieved by adding an
500 ´export´ attribute to the list of property attributes.
501 If you do not define a set or get handler, the property will automati‐
503 cally be only readable or writable as appropriate.
504 Gob2 also creates macros which can be used for type safe access to
506 properties through g_object_set and g_object_get. The macros are
507 called <type>_PROP_<argument name>(x) and <type>_GET_PROP_<argument
508 name>(x). They define both the string and the value part of the argu‐
509 ment. So for setting an argument of height, one would use (for object
510 type My:Object):
511 g_object_set (G_OBJECT (object),
513 MY_OBJECT_PROP_HEIGHT (7),
514 NULL);
515 And for getting, you would use:
517 int height;
519 g_object_get (G_OBJECT (object),
520 MY_OBJECT_GET_PROP_HEIGHT (&height),
521 NULL);
522 Note however that the type safety only works completely on GNU C com‐
524 pilers. The code will compile on other compilers but with minimal type
525 safety. For complete type safety it is useful to use the get/set meth‐
526 ods that are defined by using the ´export´ attribute.
527 To get bettery type safety on some of the property types, you can spec‐
529 ify the ´type´ attribute which will add casts where appropriate in code
530 dealing with this property. This is especially useful for POINTER and
531 OBJECT types. But even for others.
532 You can also override properties from parent objects (that is override
534 their implementation, not their attributes). Do this by adding the
535 special ´override´ attribute. For example if the parent object had a
536 ´height´ property then you could override it by
537 private int height;
539 property INT height
540 (override)
541 set { self->_priv->height = g_value_get_int (VAL); }
542 get { g_value_set_int (VAL, self->_priv->height); };
543 Overriding is supported since gob 2.0.10.
545
548 There is a whole array of possible methods. The three normal, "famil‐
549 iar" method types are private, protected and public. Public are
550 defined as normal functions with a prototype in the header file. Pro‐
551 tected methods are defined as normal methods (which you can call from
552 other files), but their prototype is placed in the private header file.
553 Private methods are defined as static functions with prototypes at the
554 top of the .c file. Then there are signal, virtual and override meth‐
555 ods. More on those later. You can also define init and class_init
556 methods with a special definition if you want to add code to the con‐
557 structors or you can just leave them out. You can also not define a
558 body for a method, by just using ´;´ instead of a body. This will
559 define an empty function. You can´t do this for non-void regular pub‐
560 lic, private or protected methods, however it is acceptable for non-
561 void virtual, signal and override methods.
562 Function argument lists:
564 For all but the init and class_init methods, you use the following syn‐
566 tax for arguments. The first argument can be just "self", which gob
567 will translate into a pointer to the object instance. The rest of the
568 arguments are very similar to normal C arguments. If the typename is
569 an object pointer you should use the syntax defined above with the
570 words separated by ´:´
571 <type> <argument id>
572 or
573 <type> <argument id> (check <list of checks>)
574 The checks are glib type preconditions, and can be the following:
576 "null", which tests pointers for being NULL, "type" which checks GTK+
577 object pointers for being the right type, "<test> <number>" which tests
578 numeric arguments for being a certain value. The test can be a
579 <,>,<=,>= != or ==. Example:
580 public int
582 foo (self,
583 int h (check > 0 < 11),
584 Gtk:Widget *w (check null type))
585 This will be the prototype of a function which has a self pointer as
588 the first argument, an integer argument which will be checked and has
589 to be more then 0 and less then 11, and a pointer to a GtkWidget object
590 instance and it is checked for being null and the type will also be
591 checked.
592 Function attributes:
594 For method that aren't virtual, signal or override methods, and aren't
596 init or class_init, GLib function attribute macros G_GNUC_PRINTF,
597 G_GNUC_SCANF, and G_GNUC_FORMAT can optionally be included after the
598 argument list. Simply include an ´attr´ keyword and the C code to
599 include in the file. You have to include braces and anything inside
600 the braces will be printed into the header file after the function dec‐
601 laration and before the trailing semicolon. The braces themselves are
602 not printed. For example:
603 public void
605 print (self, const char *format (check null), ...)
606 attr {G_GNUC_PRINTF(2, 3)}
607 This will produce a prototype which will generate a warning at compile
610 time if the contents of the format argument (argument number 2) aren't
611 consistent with the types and number of the subsequent variadic argu‐
612 ments (the first of which is argument number 3). Only one ´attr´ key‐
613 word per method is allowed. If you have more than one attribute to
614 include, you should put them all within the braces. Note that function
615 attributes were aded in version 2.0.16.
616 Error return:
618 Methods which have a return value, there also has to be something
620 returned if there is an error, such as if a precondition is not met.
621 The default is 0, casted to the type of the method. If you need to
622 return something else then you can specify an ´onerror´ keyword after
623 the prototype and any optional function attribute macros, and after
624 that a number, a token (an identifier) or a bit of C code enclosed in
625 braces {}. The braces will not be printed into the output, they just
626 delimit the string. For example:
627 public void * get_something (self, int i (check >= 0)) onerror NULL {
629 ...
630 }
631 The onerror value is also used in overrides that have a return value,
633 in case there isn´t a parent method, PARENT_HANDLER will return it.
634 More about this later.
635 Default return:
637 Some signal and virtual methods have a return type. But what happens
639 if there is no default handler and no one connects to a signal. GOB2
640 will normally have the wrappers return whatever you specify with
641 onerror or ´0´ if you haven´t specified anything. You can also specify
642 a default return value with the keyword ´defreturn´. It´s use is iden‐
643 tical to the use of onerror, and you can in fact use both at the same
644 time. Example
645 virtual int get_some_int (self) onerror -1 defreturn 10 ;
647 That is an empty virtual method (in C++ terms a pure virtual). If you
649 never specify any handler for it in the derived children it will just
650 return 10.
651 Constructor methods:
653 There are two methods that handle the construction of an object, init
655 and class_init. You define them by just using the init or class_init
656 keyword with an untyped argument in the argument list. The argument
657 will be usable in your function as a pointer to your object or class
658 depending if it´s init or class_init. For example:
659 init (self) {
661 /* initialize the object here */
662 self->a = 9;
663 self->b = 9;
664 }
665 class_init (class) {
667 /* initialize the class, this is rarely needed */
668 class->blah = NULL;
669 }
670 The class_init function is very rarely needed as all standard class
672 initialization is taken care of for you by gob itself. The init func‐
673 tion should on the other hand be used whenever you need to construct or
674 initialize anything in the object to put it into a sane state.
675 Constructor, dispose, finalize methods:
677 Since 2.0.16, you can also easily add code to the object's constructor,
679 dispose, and finalize methods. See GObject documentation on how these
680 are run. The code you add will be run before calling the parents func‐
681 tion for dispose and finalize, and after the parent function for con‐
682 structor. The syntax is just like init and class_init. For example:
683 constructor (self) {
685 /* constructor method */
686 }
687 dispose (self) {
689 /* dispose method */
690 }
691 finalize (self) {
693 /* finalize method */
694 }
695 You can also just override those methods as usual, but the above is
697 much easier and nearly as flexible.
698 Virtual methods:
700 Virtual methods are basically pointers in the class structure, so that
702 one can override the method in derived methods. That is to implement
703 the method in a derived class, you must then use an override method
704 (more on those later). They can be empty (if you put ´;´ instead of
705 the C code). A wrapper will also be defined which makes calling the
706 methods he same as public methods. This type of method is just a lit‐
707 tle bit "slower" then normal functions, but not as slow as signals.
708 You define them by using "virtual" keyword before the prototype. If
709 you put the keyword "private" right after the "virtual" keyword, the
710 wrapper will not be a public method, but a private one. You can do the
711 same with "protected" to make a protected wrapper.
712 Signals:
714 Signals are methods to which the user can bind other handlers and over‐
716 ride the default handler. The default handler is basically the method
717 body. This is the most versatile and flexible type of a method and
718 also the slowest. You need to specify a whole bunch of things when you
719 define a signal. One thing is when the default handler will be run,
720 first or last. You specify that by "first" or "last" right after the
721 "signal" keyword. Then you need to define the GObject enum types
722 (again without the G_TYPE_ prefix). For that you define the return
723 types and the types of arguments after the "self" pointer (not includ‐
724 ing the "self" pointer). You put it in the following syntax "<return
725 type> (<list of arguments>)". If the return type is void, the type
726 should be "NONE", the same should be for the argument list. The rest
727 of the prototype is the same as for other method types. The body can
728 also be empty, and also there is a public method wrapper which you can
729 use for calling the signal just like a public method. Example:
730 signal first INT (POINTER, INT)
732 int do_something (self, Gtk:Widget *w (check null type), int length)
733 {
734 ...
735 }
736 or
738 signal last NONE (NONE) void foo (self);
740 If you don´t want the wrapper that emits the signal to be public, you
743 can include the keyword "private" after the "signal" keyword. This
744 will make the wrapper a normal private method. You can also make a
745 protected wrapper by using "protected" instead of "private".
746 If you don´t define a "first" or a "last", the default will be taken as
748 "last".
749 You can also add additional flags. You do this just like with the
751 argument flags, although this is probably very rare. These are the
752 G_SIGNAL_* flags, and you can add them without the G_SIGNAL_ prefix
753 into a parenthesis, just after the "signal" keyword. By default all
754 public signals are G_SIGNAL_ACTION.
755 Also gob2 creates a wrapper macros for typesafe signal connection.
757 That is you will be warned by the compiler if you pass a callback that
758 is not the correct prototype. This will again only warn you on gcc,
759 but it will compile without warning on another compiler. So as with
760 all the typesafety hacks in gob, it is better to test your objects
761 under gcc to get any warnings even if you are using a different com‐
762 piler in the end.
763 The methods that are created for you are:
765 <class_name>_connect__<signal_name> (<object>, <callback>, <data>)
767 <class_name>_connect_after__<signal_name> (<object>, <callback>, <data>)
768 <class_name>_connect_data__<signal_name> (<object>, <callback>, <data>,
769 <destroy_notify>, <flags>)
770 These three functions correspond to the g_signal_connect, g_signal_con‐
773 nect_after and g_signal_connect_data functions that you would normally
774 use, except they are for a specific signal. Also do note the two
775 underscores between the method name and the signal name. For example
776 to connect the signal "foo" on the object "Test:Object" you would do:
777 test_object_connect__foo (object, callback, data);
779 To use BOXED in the signal arguments you need to tell gob which type of
782 boxed argument you want to use. For this you can just add
783 BOXED_GTK_TYPE_STRING instead of BOXED. For example
784 BOXED_GTK_TYPE_TREE_ITER for GtkTreeIter. This works since version
785 2.0.13.
786 Override methods:
788 If you need to override some method (a signal or a virtual method of
790 some class in the parent tree of the new object), you can define and
791 override method. After the "override" keyword, you should put the
792 typename of the class you are overriding a method from. Other then
793 that it is the same as for other methods. The "self" pointer in this
794 case should be the type of the method you are overriding so that you
795 don´t get warnings during compilation. Also to call the method of the
796 parent class, you can use the PARENT_HANDLER macro with your arguments.
797 Example:
798 override (Gtk:Container) void
800 add (Gtk:Container *self (check null type), Gtk:Widget *wid (check null type))
801 {
802 /* some code here */
803 PARENT_HANDLER(self, wid);
804 }
805 If the function has a return value, then PARENT_HANDLER is an expres‐
807 sion that you can use. It will return whatever the parent handler
808 returned, or the "onerror" expression if there was no parent handler.
809 Method names:
811 Inside the code, aliases are set for the methods, so that you don´t
813 have to type the class name before each call, just type self_ instead
814 of the name of the class. So to call a method called blah, you would
815 use the name self_blah. Example:
816 private int
818 foo (self)
819 {
820 return self->len;
821 }
822 private int
824 bar (self, int i)
825 {
826 return self_foo (self) + i;
827 }
828
832 You should define a new method which should be a normal public method.
833 Inside this method, you can use the GET_NEW macro that is defined for
834 you and that will fetch a new object, so a fairly standard new method
835 would look like:
836 public GObject *
838 new (void) {
839 GObject *ret = GET_NEW;
840 return G_OBJECT (ret);
841 }
842 You should not a subtle peculiarity of the GObject system here. If
845 there is any code inside the G_OBJECT macro argument, it will get exe‐
846 cuted multiple times. This means that things such as G_OBJECT(GET_NEW)
847 would actually create 4 objects, leaking 3 of them. A good rule (as
848 with anywhere in C) is to be careful with all macros.
849
852 Self alias casts:
853 There are some standard casts defined for you. Instead of using the
855 full macros inside the .c file, you can use SELF, IS_SELF and
856 SELF_CLASS. Using these makes it easier to for example change class
857 names around.
858 Self alias types:
860 There are also the Self and SelfClass types inside your .c file. These
862 serve the same function as the above, they make it easier to type and
863 easier to change typenames around which can help a lot during prototyp‐
864 ing stage. However you should note that the Self type should not be
865 used in function prototypes as one of the arguments or as a return
866 value type. This is because this is a simple C typedef which is only
867 available inside your .c file and not in the header files. You can
868 disable both the self casting macros and the self type aliases by pass‐
869 ing --no-self-alias to gob.
870
873 Defines:
874 In your generated C file, you can use the defines GOB_VERSION_MAJOR
876 GOB_VERSION_MINOR and GOB_VERSION_PATCHLEVEL if you wish to for example
877 use a feature that is only available in some newer gob version. Note
878 however that you can only use these defines in the C code portions of
879 your .gob file, and #ifdef´s cannot span multiple functions. Check the
880 BUGS section for more on using the C preprocessor and gob.
881 Minimum version requires:
883 You can also make your .gob file require at least certain version of
885 gob. You do this by putting ´requires x.y.z´ (where x.y.z is the ver‐
886 sion number) outside of any C block, comment or class, usually you
887 should make this the first line in the file or close to the top. If
888 gob finds this and the version of gob used to compile the code is lower
889 then that listed in the require, gob will generate an error and exit.
890 For example to require that gob2 version 2.0.0 or higher be used to
891 compile a file, put this at the top of that file:
892 requires 2.0.0
894
898 You can create new GObject ENUM, FLAGS and GError types for use in your
899 classes easily. Glib includes some utilities for handling these, how‐
900 ever it may be cleaner to use the below specified way in your classes.
901 It also then doesn´t require any Makefile setup. Make sure this is
902 defined in the same section as the class, that is not in any of the
903 ´%?{´ ´%}´ sections.
904 You use the keywords ´enum´ ´flags´ and ´error´ as you would use the
906 ´class´ keyword. Then you give a prefix for the values in the enumera‐
907 tion. Then you define a list of values just like in C. For ´enum´
908 types you can also specify the values assigned to each string. Then
909 you specify the type in the standard gob style of specifying types.
910 Here are a few examples of all of these:
911 enum LAME_CLIENT {
913 IS_CONNECTED,
914 NONE = 9,
915 LAST
916 } Test:Enum;
917 flags BUGA_BUGA {
919 ONE,
920 TWO,
921 MANY,
922 } Some:Flags;
923 error TEST_OBJECT_ERROR {
925 BAD_THIS,
926 BAD_THAT
927 } Test:Object:Error;
928 This will for example define an enum that is equivalent to the follow‐
931 ing C code:
932 typedef enum {
934 LAME_CLIENT_IS_CONNECTED,
935 LAME_CLIENT_NONE = 9,
936 LAME_CLIENT_LAST
937 } TestEnum;
938
942 There is a C++ mode so that gob creates C++ compiler friendly files.
943 You need to use the --for-cpp argument to gob. This will make the gen‐
944 erated file have a .cc instead of a .c extension, and several things
945 will be adjusted to make it all work for a C++ compiler. One thing
946 that will be missing is an alias to the new method, as that clashes
947 with C++, so instead you´ll have to use the full name of the method
948 inside your code. Also note that gob does not use any C++ features,
949 this option will just make the generated code compile with a C++ com‐
950 piler.
951
954 The get_type is not really a method, but a function which initializes
955 your object. Recently objects appeared which require you to make a
956 custom get_type function. So it is possible to override this function.
957 To do so, just define a new public method called get_type, with no
958 arguments. Example:
959 public GType
961 get_type (void)
962 {
963 /* code goes here */
964 return some_type;
965 }
966
970 Currently gob will only allow you to implement interfaces (that is,
971 define new classes which implement an interface) and doesn´t yet have
972 support for making new interfaces, but this will be coming at some
973 point in the future.
974 To define a class that implements an interface add a class flag ´inter‐
976 face´ with the type name of the interface as an argument. Then to
977 implement a specific method of the interface, just add ´interface
978 <typename>´ before the method definition. The method can, and probably
979 should be, private.
980 The following example implements a new object, that implements the
982 Gtk:Tree:Model interface and implements the get_flags method of that
983 interface. Do note that except for standard (GTK+ and glib) specific
984 interfaces which seem to have a non-standard name for the interface
985 structure, the structure should end with and Iface, if you are imple‐
986 menting an interface. That is for example for the Gtk:Tree:Model, the
987 structure containing the table of methods should be named GtkTreeMod‐
988 elIface.
989 class Some:Object from G:Object
990 (interface Gtk:Tree:Model)
991 {
992 /* function implemented for the Gtk:Tree:Model interface */
993 interface Gtk:Tree:Model
994 private GtkTreeModelFlags
995 get_flags (Gtk:Tree:Model *self (check null type))
996 {
997 /* Here would be the implementation */
998 return (GtkTreeModelFlags)0;
999 }
1000 }
1001 If you want to implement multiple interfaces just list more class flag
1004 lines as follows:
1005 class Some:Object from G:Object
1007 (interface Gtk:Tree:Model)
1008 (interface Gtk:Editable)
1009 {
1010 /* ... */
1011 }
1012
1016 If you want to build a BonoboObject class gob2 has direct support for
1017 these. Just create a new object that derives from Bonobo:Object. Then
1018 use a "BonoboObject" class flag with the interface name as an argument.
1019 The interface name should be as you would type it in C, that is with
1020 underscores as namespace separators. Then you add the methods (using
1021 exact same names as in the idl file) and prepend those methods with a
1022 BonoboObject keyword. For example imagine you have an interface
1023 GNOME/Foo/SomeInterface, with a method fooBar that takes a single
1024 string:
1025 class Foo:Some:Interface from Bonobo:Object
1027 (BonoboObject GNOME_Foo_SomeInterface) {
1028 BonoboObject
1030 private void
1031 fooBar (PortableServer_Servant servant,
1032 const CORBA_char *string,
1033 CORBA_Environment *ev)
1034 {
1035 Self *self = SELF (bonobo_object_from_servant (servant));
1036 /* your code here */
1038 }
1039 /* rest of class */
1041 }
1042 Note that the implementation method can be private, in fact that´s
1044 probably a good idea to do. It won´t work to make this a signal, it
1045 can however be a virtual. Note that the method prototype must match
1046 the one from the interface header file, or you will get a bad assign‐
1047 ment warning. You should check the header file generated by orbit-idl
1048 and see the epv structure for the correct prototypes if you can´t fig‐
1049 ure them out from the idl itself. Also note that the first argument is
1050 not "self", but the servant and you must use bonobo_object_from_servant
1051 function to get the actual object pointer.
1052
1055 Gob can simplify writing a libglade class. Just create a new object
1056 that derives from a GtkContainer widget. Then use a "GladeXML" class
1057 flag with the glade file name, root widget and optional domain as
1058 arguments between double quotes. For example:
1059 class My:Glade from Gtk:Window (GladeXML "gob-libglade.glade" "root")
1061 {
1062 ....
1063 }
1064 Note however that then "gob-libglade.glade" would have to be in the
1066 current directory. You could specify a path, but that may not work for
1067 all installations. You can replace the glade filename with a token to
1068 be used in the generated .c file and you can then have a macro with the
1069 filename, as follows:
1070 class My:Glade from Gtk:Window (GladeXML GLADE_FILE "root")
1072 {
1073 ....
1074 }
1075 And somewhere in your header files you would have
1077 #define GLADE_FILE "/path/to/file.glade"
1079 You can declare widgets as data members by adding a 'GladeXML' to the
1082 definition.
1083 private Gtk:Button * button1 GladeXML;
1085 This will automatically set the "button1" from the GladeXML file.
1087 All signals created with glade are automatically connected if you
1089 defined those class methods in your class. For example suppose in
1090 glade that we set the "connect" signal on button1 to go to on_but‐
1091 ton1_clicked, then in our gob file we can just write:
1092 public void
1094 on_button1_clicked(self, GtkButton * button)
1095 {
1096 }
1097 See the examples directory for a full example. Note that this feature
1100 requires version at least 2.0.12.
1101
1105 Gob will need to define some local variables and functions in the gen‐
1106 erated files, so you need to take some precaution not to conflict with
1107 these. The general rule of thumb is that all of these start with three
1108 underscores. There is one, "parent_class" which doesn´t because it´s
1109 intended for use in your code. For virtuals or signals, you cannot use
1110 the identifier __parent__ which is used for the parent of the object.
1111 You should actually never access __parent__ either as it not guaranteed
1112 that it will stay named this way. Data members cannot be named __par‐
1113 ent__ nor _priv. For methods, you cannot use the identifiers "init" or
1114 "class_init" unless you mean the constructor methods. You shouldn´t
1115 generally use 3 underscores even in override method argument lists and
1116 virtual and signal method names as it might confuse the PARENT_HANDLER
1117 macro. In fact avoiding all names with three underscores is the best
1118 policy when working with gob.
1119 There are a couple of defines which you shouldn´t be redefining in the
1121 code or other headers. These are SELF, IS_SELF, SELF_CLASS, SELF_TYPE,
1122 ARG, VAR, PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR
1123 and GOB_VERSION_PATCHLEVEL.
1124 As for types, there are Self and SelfClass types which are only defined
1126 in your source files. Their generation (just like the generation of
1127 the SELF macros) can be turned off, see command line options.
1128
1131 If you want to use gtk-doc style inline documentation for your objects,
1132 you can do one of two things. First, you could include the inline doc‐
1133 umentation comments in your %{ %} section which will then be put verba‐
1134 tim into the output source file. This is the way you should use for
1135 functions you define outside of the class.
1136 For class methods, you should use a gtk+ style comment, however it can
1138 be indented any number of tabs or spaces and you can use the short
1139 method name without the type prefix. Gob will automatically try to
1140 extract these and translate to full names and put them in the output
1141 source file. An example would be:
1142 class Gtk:Button:Example from Gtk:Button {
1144 /**
1145 * new:
1146 *
1147 * Makes a new #GtkButtonExample widget
1148 *
1149 * Returns: a new widget
1150 **/
1151 public
1152 GtkWidget *
1153 new(void)
1154 {
1155 return (GtkWidget *)GET_NEW;
1156 }
1157 }
1158 If the function you are documenting is a signal or a virtual then it
1160 will be documenting the wrapper that starts that virtual function or
1161 emits that signal.
1162
1165 Sometimes you may need to use an object of type MyObjectA in the MyOb‐
1166 jectB class and vice versa. Obviously you can´t include headers for
1167 both. So you need to just declare the typedef in the header of A for
1168 B, and the other way around as well. The headers generated include a
1169 protecting define before it declares the typedef. This define is the
1170 __TYPEDEF_<upper case object name>__. So inside my-object-a.h there
1171 will be this:
1172 #ifndef __TYPEDEF_MY_OBJECT_A__
1174 #define __TYPEDEF_MY_OBJECT_A__
1175 typedef struct _MyObjectA MyObjectA;
1176 #endif
1177 Now instead of including my-object-a.h in the header section of
1179 my-object-b.gob, just copy the above code there and you´re set for
1180 using MyObjectA as a type in the method parameters and public types.
1181 Another way to get out of this problem is if you can use those types
1183 only in the private members, in which case they won´t be in the gener‐
1184 ated public header.
1185
1188 If you are using normal makefiles, what you need to do is to add a
1189 generic rule for .gob files. So you would include the following in the
1190 Makefile and then just use the .c and .h files as usual (make sure the
1191 space before the ´gob2´ is a tab, not spaces):
1192 %.c %.h %-private.h: %.gob
1194 gob2 $<
1195
1199 This is a little bit more involved. Basically the first thing to do is
1200 to check for GOB2 in your configure.in file. You can use the supplied
1201 m4 macro which will also check the version of gob. Basically you
1202 include this:
1203 GOB2_CHECK([2.0.0])
1205 This will replace @GOB2@ in your makefiles with the full path of gob2.
1207 Thus when adding the generic rule to your Makefile.am file, it should
1208 look like:
1209 %.c %.h %-private.h: %.gob
1211 @GOB2@ $<
1212 For Makefile.am you have to set up a couple more things. First you
1215 have to include the generated .c and .h files into BUILT_SOURCES vari‐
1216 able. You have to include both the .gob and the .c and .h files in the
1217 SOURCES for your program.
1218
1221 When nothing has changed you might not really want to rebuild every‐
1222 thing and gob provides options --no-touch (since 2.0.13) and
1223 --no-touch-headers to avoid this. When working with build systems such
1224 as automake you have to be more careful as just using those options can
1225 cause automake to get confused and you will need to use something like
1226 the following:
1227 foo_SOURCES = foo.gob foo.gob.stamp foo.c foo.h foo-private.h
1229 BUILT_SOURCES = foo.gob.stamp
1230 MAINTAINERCLEANFILES = foo.gob.stamp
1231 %.gob.stamp: %.gob
1233 @GOB2@ --no-touch $<
1234 @touch $@
1235
1239 GOB does several things to make debugging the code easier. First it
1240 adds preprocessor commands into the output c file that point to the
1241 correct places in your .gob input file. However sometimes there might
1242 be some bigger confusion and this is just not helpful. In this case
1243 you will probably want to have gcc point you directly at the generated
1244 files. For this use the --no-lines command line option. You should
1245 also note that these commands are not generated for the public header
1246 file at all. If there is an error which points you to the public
1247 header file, make sure you fix this error in the .gob file, otherwise
1248 your changes will not have any effect after gob recompiles the sources
1249 again.
1250 Sometimes you might want to know which method you are in for some
1252 debugging output. GOB will define __GOB_FUNCTION__ macro, which is
1253 just a string constant with a pretty name of the method.
1254
1257 It is possible to have your .gob file also preprocessed by m4. This is
1258 useful if you have a lot of files and you´d like to have some pre‐
1259 processor put in some common features. All you have to do is add --m4
1260 to the command line of gob2 and gob2 will first run your file through
1261 m4. You can print the directory that is searched for m4 files by run‐
1262 ning "gob2 --m4-dir"
1263 All the arguments after --m4 will be passed to m4 itself, so it has to
1265 be the last gob2 argument on the command line. This way you can spec‐
1266 ify arbitrary options to pass to m4.
1267
1270 The lexer does not actually parse the C code, so I´m sure that some
1271 corner cases or maybe even some not so corner cases of C syntax might
1272 confuse gob completely. If you find any, send me the source that makes
1273 it go gaga and I´ll try to make the lexer try to handle it properly,
1274 but no promises.
1275 Another thing is that gob ignores preprocessor macros. Since gob
1277 counts braces, the following code won´t work:
1278 #ifdef SOME_DEFINE
1280 if(foo) {
1281 #else
1282 if(bar) {
1283 #endif
1284 blah();
1285 }
1286 To make this work, you´d have to do this:
1288 #ifdef SOME_DEFINE
1290 if(foo)
1291 #else
1292 if(bar)
1293 #endif
1294 {
1295 blah();
1296 }
1297 There is no real good way we can handle this without parsing C code, so
1299 we probably never will. In the future, I might add #if 0 as a comment
1300 but that´s about as far as I can really take it and even that is prob‐
1301 lematic. Basically, if you use gob, just don´t use the C preprocessor
1302 too extensively. And if you use it make sure that you do not cross the
1303 boundaries of the C code segments.
1304 Comments will not get through to the generated files unless inside C
1306 code. This is not the case for gtk-doc style comments which are sup‐
1307 ported.
1308 The short name aliases are actually implemented as pointers to func‐
1310 tions. Thus if you want to get the pointer of a function using the
1311 short name alias you can´t use the ´&´. Thus:
1312 void (*foo)(Self *);
1314 /* this will NOT work */
1316 foo = &self_short_name;
1317 /* this will work */
1319 foo = self_short_name;
1320 /* Both of these will work */
1322 foo = &my_class_long_name;
1323 foo = my_class_long_name;
1324
1328 George Lebl <jirka@5z.com>
1329 GOB2 Homepage: http://www.jirka.org/gob.html
1331 GOB2 2.0.19 GOB2(1)