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