X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/714b58ab4606ed4d40cec3702cb378938f8c883f:/doc/gob.1.in..7231d76fbf4ae0b501af648e1216b88714aa7353:/doc/static/gitweb/gitweb.css diff --git a/doc/gob.1.in b/doc/gob.1.in deleted file mode 100644 index 81aa107..0000000 --- a/doc/gob.1.in +++ /dev/null @@ -1,1055 +0,0 @@ -.\" -.\" gob manual page -.\" (C) 1999 George Lebl -.\" -.\" This manual page is covered by the terms of the GNU General -.\" Public License. -.\" -.TH GOB 1 "GOB @VERSION@" -.SH NAME -GOB \- The GTK+ Object Builder -.SH SYNOPSIS -.PP -.B gob -[ option ] ... -file -.SH DESCRIPTION -.PP -GTK+ Object Builder is a simple preprocessor for easily creating -GTK+ objects. It does not parse any C code and ignores any C errors. It -is in spirit similar to things like lex or yacc. - -.SH OPTIONS -.PP -.TP -.B -? -h --help -Display a simple help screen. -.TP -.B --version -Display version information (note, --version was not added until 0.92.0) -.TP -.B -w --exit-on-warn -Exit with an error code even when you encounter a warning. -.TP -.B --no-exit-on-warn -Exit with an error only on errors, not on warnings, this is the default. -.TP -.B --for-cpp -Generate C++ code. -.TP -.B --no-extern-c -Never add the extern "C" to the header. -.TP -.B --no-gnu -Never generate any code with GNU C extensions. However all the GNU C -extensions are always wrapped in #ifdef __GNUC__, so code using them compiles -correctly even on non-GNU compilers. This option is for purists only. -(using GNU extensions some warnings are eliminated, some ugly hacks and there -is better argument type safety, so it's good to use them) -.TP -.B --no-touch-headers -Don't touch the generated header file unless it really changed, this avoids -spurious rebuilds, but can confuse some make systems (automake in particular), -so it is not enabled by default. Private header is still touched even if -unchanged however. -.TP -.B --always-private-header -Always create a \fB-private.h\fR file, even if it would be empty. -Otherwise, it is only created when there are private data members in the class. -This option implicitly negates --no-private-header -.TP -.B --no-private-header -Never create a private header file. If we use any private data members, -define the private data structure at the point in the .c source where -the class definition begins. This option implicitly negates ---always-private-header -.TP -.B -n --no-write -Do not write any output files, just check syntax of the input file. -.TP -.B --no-lines -Do not print out the '#line' statements into the output. Useful for debugging -the auto-generated generated code. -.TP -.B --no-self-alias -Do not create the Self and SelfClass type aliases and the SELF, IS_SELF -and SELF_CLASS macros. -.TP -.B --no-kill-underscores -Do not remove the initial underscore from method names. -.TP -.B --always-private-struct -Always include the private pointer in the public header file. This is useful for -files which are part of a library and you want to reserve the right to add some -private data members without breaking binary compatibility. - -.SH TYPENAMES -.PP -Because we need to parse out different parts of the typename, sometimes you -need to specify the typename with some special syntax. Types are specified in -capitalized form and words are separated by ':'. The first word of the type -(which can be empty) is the "namespace". This fact is for example used for the -type checking macro and the type macro. For "Gtk:New:Button", the macros will -be GTK_IS_NEW_BUTTON and GTK_TYPE_NEW_BUTTON. This colon separated format of -typenames is used in the class declaration header and for method argument -types. - -.SH OUTPUT FILES -.PP -The filenames are created from the typename. The words are -separated by '-' and all in lower case. For example for an object named -"Gtk:New:Button", the files are \fBgtk-new-button.c\fR and -\fBgtk-new-button.h\fR. -If you are using C++ mode, the output .c file will in fact be a .cc file. -If you have any private data members, a private header file will also -be created, called \fB-private.h\fR (for the example above it -would be gtk-new-button-private.h). -The public header file is created to be human readable and to be used as a -reference to the object. The .c source file is not created as a human -readable source and is littered with #line statements, which make the -compiler attempt to point you to the right line in your .gob file in -case of parsing errors. The output should not be edited by hand, and -you should only edit the .gob file. - -.SH INCLUDING NORMAL C CODE IN THE OUTPUT FILES -.PP -To include some code directly in the output C file begin with '%{' -on an empty line and end the code with a '%}' on an empty line. These -sections will appear in the output files in the order they are given. -There are several other \fIsections\fR to which you can put code. You can -put it in the 'header' section (which can be abbreviated 'h') and it will -go into the public header file. You can also put it in the 'privateheader' -section (abbreviated 'ph') which will make the code go into the private -header file. Sometimes you want some code (other includes) to appear before -the extern "C" and the protecting define. To do this you can put them -into the 'headertop' (or 'ht') section. You may wish to include code or -comments in all the files, which you can do by putting them into the 'all' -(or 'a') section. Similarly, code you wish to appear at the top of all -files go in the 'alltop' (or 'at') section. For example: -.nf - - %alltop{ - /* this will be on top of all output files */ - %} - - %headertop{ - /* this will be on top of the public header */ - %} - - %privateheader{ - /* this will go into the private header file */ - %} - - %h{ - /* will be included in the header */ - void somefunc(int i); - %} - - %a{ - /* will be included in all files */ - %} - - %{ - /* will be included in the C file */ - void somefunc(int i) - { - /* some code */ - } - %} - -.fi - -.SH INCLUDE FILES -.PP -Gob will automatically include the class header file at the top of the .c -source file. If you wish to include it somewhere else, put the include -into some %{ %} section above the class definition, and gob will not include -it automatically. This way you can avoid circular includes and control -where in the file do you want to include the header. -.PP -If you made any data members private, gob will also create a source file -that will be called \fB-private.h\fR. Same rule as above applies -for this just as it does for the regular header file. If you do explicitly -include the regular header file, you should always include this private -header file below it. That is, if you use any private data members. If you -don't, the private header file automatically includes the public header file, -and thus the public header file will be indirectly included at the very top -of the file. - -.SH MAKING A NEW CLASS -.PP -The class header: -.PP -There can be only one class per input file. Defining a class -is sort of like in Java, you define the class and write inline code -directly into the class definition. To define a class you need to specify -the new object name and the name of the object from which it is derived -from, such as this "class from { }". -For example: -.nf - - class Gtk:New:Button from Gtk:Button { - - } - -.fi -.PP -Data members: -.PP -There are five types of data members. Three of them are normal data numbers, -one is class wide (global) in scope and one is a virtual one, usually linked to -a normal data member or a class wide data member. The three normal data -members are public, protected and private. Public and protected are basically -just entries in the object structure, while private has it's own dynamically -allocated private structure. Protected members are always put after the public -one in the structure and are marked protected in the header file. There is -only one identifier allowed per typename unlike in normal C. Example: -.nf - - public int i; - private GtkWidget *h; - protected long k; - -.fi -.PP -Public and protected data members are accessed normally as members of -the object struct. Example where 'i' is as above a public data member: -.nf - - object->i = 1; - -.fi -.PP -The private data members are defined in a structure which is only available -inside the .c file, or by including a private header file. You must access -them using the structure _priv. Example -where 'h' is the private data member (as in the above example): -.nf - - object->_priv->h = NULL; - -.fi -The _priv structure is defined in the \fB-private.h\fR. -This file is automatically included if you don't include it yourself. You -should always explicitly include it in your .gob file if you explicitly also -include the main header file. The reason it is a separate header file is -that you can also include it in other places that need to access this objects -private data, such as if you have the majority of functionality of an object -in a separate .c file. Or if a derived object needs to access the protected -methods. -.PP -In case you use the \fB--no-private-header\fR option, no -private header file is created and you can only access the _priv pointer -below the class definition in the .gob file. -.PP -Also note that this structure is dynamically allocated, and is freed in the -finalize handler. If you override the finalized handler, your code will be -run first and only then will the _priv structure be freed. -.PP -Classwide data members: -.PP -Sometimes you want a datamember to be shared by all objects. You then need -the "classwide" scope keyword. So for example the following adds a global -member foo: -.nf - - classwide int foo; - -.fi -To access the member you do the standard voodoo of getting the class from the -object and casting it to your class pointer. Thus the following would work: -.nf - - SELF_CLASS(GTK_OBJECT(object)->klass)->foo = 20; - -.fi -.PP -Automatic Initialization (0.93.0 and higher only): -.PP -You can automatically initialize the public private and protected data members -without having to add an init method. The advantage here is that -initialization is kept close to the definition of the data member and thus -it's easier to check. To do this, just add a '=' followed by a number or -a token. It is also possible to include arbitrary C code for more elaborate -initializations by putting it all in curly braces. Note that the curly braces -will not be printed into the output, but since gob does not C parsing it needs -them to figure out where the C code ends. The code will be inserted into the -init method, above the user defined body. So for example the following -will initialize an integer to -1 and a string with a newly allocated string -of "hello". -.nf - - public int foo = -1; - private char *bar = {g_strdup("hello")}; - -.fi -.PP -Automatic Destruction (0.93.0 and higher only): -.PP -Most data stored as pointers needs to have a function called when the object -is destroyed, to either free it or give up a reference. Gob will let you -define a function to be called on the data the object is destroyed. This is -achieved by putting 'destroywith' followed by a function name after the -variable definition. It is only called if the data you defined this on -is not NULL, so you cans specify functions which do not handle NULL. It -is very much like the GDestroyNotify function used in GTK+ and glib in many -places. Unlike many other places, gob will not enforce any kind of type -safety here so be a little bit more careful. Any function you give it will -be called as a "void function(void *)". It will in fact be cast into such -a form before called. This is to avoid spurious warnings for gtk calls to -subclass methods. The function needs not be of that form exactly, it just has -to take one argument which is the pointer to the data. You should also not -define this on any non-pointer data as the results may be undefined. -Example: -.nf - - public Gtk:Widget *window = NULL - destroywith gtk_widget_destroy; - public char *foo = {g_strdup("bar")} - destroywith g_free; - -.fi -Note that the function name you give must be a real function and not macro. -Also note that this is always called in the "destroy" method of GtkObject. -It is always called after any user defined body of the destroy handler. -.PP -Sometimes you may want to run arbitrary code on destruction. While this can -be perfectly well done in the destroy handler. Depending on the style you -may want to include all destruction/initialization code together with the -definition of the data member. Thus you may want to put arbitrary code which -will then be inserted into the "destroy" method of GtkObject. This can be -done with the "destroy" keyword followed by arbitrary code in curly braces. -Inside this code a macro called VAR will be define which refers to your -variable. So for example destroying a GString can be either done with -a helper routine or the following code: -.nf - - public GString *string = {g_string_new(NULL)} - destroy { - if(VAR) g_string_free(VAR, TRUE); - }; - -.fi -The thing to remember with these is that there are many ways to do this -and you'd better be consistent in your code in how you use the above things. -Also defining a helper routine that will do the destruction will be a nicer -thing to do if that's a possibility. The "destroy" keyword with code does -take up more space in the file and it may become more cluttered. -.PP -The data is zeroed out after being destroyed. This is to make debugging easier -in case your code might try to access an already destroyed object. In case -you have overridden the destroy method, your code will be run first and -only then will the destructors be called. You should not however make any -assumptions about the order at which the destructors are called. If you have -interdependencies between destructors for different data members, you will -have to do this in your own destroy override function. -.PP -GTK+ Arguments: -.PP -The fourth type of a data member an argument type. It is a named data member -which is one of the features of the GTK+ object system. You need to define a -get and a set handler. They are fragments of C code that will be used to get -the value or set the value of the argument. Inside them you can use the define -ARG to which you assign the data or get the data. You can also use the -identifier "self" as pointer to the object instance. The type is defined as -one of the gtk type enums, but without the GTK_TYPE_ prefix. For example: -.nf - - public int height; - argument INT height set { self->height = ARG; } get { ARG = self->height; }; - -.fi -.PP -If you don't define a set or a get handler it will be a read-only -or a write-only argument. If you want to add extra argument flags, add -them into parenthesis after the argument keyword, separated by '|' and -without the GTK_ARG_ prefix. For example: -.nf - - public int height; - argument (CONSTRUCT) INT height get { ARG = self->height; }; - -.fi -This makes the argument settable even before the object is constructed, so -that people can pass it to gtk_object_new function. Useful is also -CONSTRUCT_ONLY flag which makes the argument only available during -construction of the object. -.PP -Since 0.92.1, gob creates macros which can be used for type safe access to -gtk arguments. The macros are called _ARG_(x) and -_GET_ARG_(x). They define both the string and the -value part of the argument. So for setting an argument of height, one would -use (for object type My:Object): -.nf - - gtk_object_set (GTK_OBJECT (object), - MY_OBJECT_ARG_HEIGHT (7), - NULL); - -.fi -And for getting, you would use: -.nf - - int height; - gtk_object_set (GTK_OBJECT (object), - MY_OBJECT_GET_ARG_HEIGHT (&height), - NULL); - -.fi -Note however that the type safety only works completely on GNU C compilers. -The code will compile on other compilers but with minimal type safety. -.PP -To get good type safety on POINTER types however, you should specify -an optional C type that gob should use. For other then POINTER types -this is redundant but possible. To do this, place '(type )' -right after the GTK+ type. Example: -.nf - - argument POINTER (type char *) foo set { /* foo */ } get { /* bar */ }; - -.fi -.PP -Sometimes it can become tiresome to type in the set and get handlers if -they are trivial. So gob since version 0.93.0 provides automatic argument -linking to data members. There are three different cases it handles, direct -link (keyword 'link'), string linking (keyword 'stringlink') and object -linking (keyword 'objectlink'). You just place the keyword after the argument -name instead of the get/set handlers. It will link to a data member of the -same name that was defined earlier in the input file. Best is to see examples: -.nf - - public int foo; - argument INT foo link; - -.fi -is just like -.nf - - public int foo; - argument INT (type int) foo - get { ARG = self->foo; } - set { self->foo = ARG; }; - -.fi -Similarly, -.nf - - private char * foo; - argument POINTER foo stringlink; - -.fi -is just like -.nf - - private char * foo; - argument POINTER (type char *) foo - get { - ARG = g_strdup(self->_priv->foo); - } set { - g_free(self->_priv->foo); - self->_priv->foo = g_strdup(ARG); - } - -.fi -And for the objectlink we would have: -.nf - - public Gtk:Object * foo; - argument POINTER foo objectlink; - -.fi -is just like -.nf - - protected Gtk:Object * foo; - argument POINTER (type Gtk:Object *) foo - get { - ARG = self->foo; - } set { - if(self->foo) - gtk_object_unref(self->foo); - self->foo = ARG; - if(self->foo) - gtk_object_ref(self->foo); - } - -.fi -.PP -As you see it will handle NULLs correctly (for the string, g_free and g_strdup -handle NULLs). And it will also handle private, protected and public members. -For objectlink, just a pointer is returned on get, if you wish to keep it around, -you should call gtk_object_ref on it. For stringlink, get makes a copy of -the string which you should free after use. This is the behaviour since 1.0.2. -.PP -Methods: -.PP -There is a whole array of possible methods. The three normal, -"familiar" method types are private, protected and public. Public are -defined as normal functions with a prototype in the header file. -Protected methods are defined as normal methods (which you can call from other -files), but their prototype is placed in the private header file. Private -methods -are defined as static functions with prototypes at the top of the .c -file. Then there are signal, virtual and override methods. More on those -later. You can also -define init and class_init methods with a special definition if you want -to add code to the constructors or you can just leave them out. -You can also not define a body for a method, by just using ';' instead of a -body. This will define an empty function. You can't do this for non-void -regular public, private or protected methods, however it is acceptable for -non-void virtual, signal and override methods. -.PP -Function argument lists: -.PP -For all but the init and class_init methods, you use the -following syntax for arguments. The first argument can be just "self", -which gob will translate into a pointer to the object instance. The rest -of the arguments are very similar to normal C arguments. If the -typename is an object pointer you should use the syntax defined above -with the words separated by ':' -.nf - -or - (check ) -.fi -.PP -The checks are glib type preconditions, and can be the following: -"null", which tests pointers for being NULL, "type" which checks GTK+ -object pointers for being the right type, " " which tests -numeric arguments for being a certain value. The test can be a <,>,<=,>= -!= or ==. Example: -.nf - - public int foo(self, int h (check > 0 < 11), Gtk:Widget *w (check null type)) - -.fi -.PP -This will be the prototype of a function which has a self pointer -as the first argument, an integer argument which will be checked and has -to be more then 0 and less then 11, and a pointer to a GtkWidget object -instance and it is checked for being null and the type will also be -checked. -.PP -Error return: -.PP -Methods which have a return value, there also has to be something -returned if there is an error, such as if a precondition is not met. The -default is 0, casted to the type of the method. If you need to return -something else then you can specify an "onerror" keyword after the -prototype and after that a number, a token (an identifier) or a bit of C -code enclosed in braces {}. The braces will not be printed into the -output, they just delimit the string. For example: -.nf - - public void * get_something(self, int i (check >= 0)) onerror NULL { - ... - } - -.fi -The onerror value is also used in overrides that have a return value, in -case there isn't a parent method, PARENT_HANDLER will return it. More about -this later. -.PP -Default return: -.PP -Some signal and virtual methods have a return type. But what happens if -there is no default handler and no one connects to a signal. GOB will -normally have the wrappers return whatever you specify with onerror or '0' -if you haven't specified anything. But since 0.93.2 you can specify a default -return value with the keyword 'defreturn'. It's use is identical to the -use of onerror, and you can in fact use both at the same time. Example -.nf - - virtual int get_some_int(self) onerror -1 defreturn 10 ; - -.fi -That is an empty virtual method (in C++ terms a pure virtual). If you never -specify any handler for it in the derived children it will just return 10. -.PP -Constructor methods: -.PP -There are two methods that handle the construction of an object, init and -class_init. You define them by just using the init or class_init keyword -with an untyped argument in the argument list. The argument will be -usable in your function as a pointer to your object or class depending if -it's init or class_init. -For example: -.nf - - init(self) { - /* initialize the object here */ - self->a = 9; - self->b = 9; - } - - class_init(class) { - /* initialize the class, this is rarely needed */ - class->blah = NULL; - } - -.fi -The class_init function is very rarely needed as all standard class -initialization is taken care of for you by gob itself. The init function -should on the other hand be used whenever you need to construct or initialize -anything in the object to put it into a sane state. Sometimes you need -some arguments, for this you should either use a construct method and a -new function like many GTK+ widgets, and/or a CONSTRUCT or CONSTRUCT_ONLY -type of an argument. -.PP -Virtual methods: -.PP -Virtual methods are basically pointers in the class structure, -so that one can override the method in derived methods. They can be empty -(if you put ';' instead of the C code). A wrapper will also be defined -which makes calling the methods he same as public methods. This type of -method is just a little bit "slower" then normal functions, but not as -slow as signals. You define them by using "virtual" keyword before the -prototype. If you put the keyword "private" right after the "virtual" -keyword, the wrapper will not be a public method, but a private one. -You can do the same with "protected" to make a protected wrapper. -.PP -Signals: -.PP -Signals are methods to which the user can bind other handlers -and override the default handler. The default handler is basically the -method body. This is the most versatile and flexible type of a method -and also the slowest. You need to specify a whole bunch of things when -you define a signal. One thing is when the default handler will be run, -first or last. You specify that by "first" or "last" right after the -"signal" keyword. Then you need to define the gtk enum types (again -without the GTK_TYPE_ prefix). For that you define the return types -and the types of arguments after the "self" pointer (not including the -"self" pointer). You put it in the following syntax " ()". If the return type is void, the type should be "NONE", -the same should be for the argument list. The rest of the prototype is -the same as for other method types. The body can also be empty, and -also there is a public method wrapper which you can use for calling the -signal just like a public method. Example: -.nf - - signal first INT(POINTER,INT) - int do_something(self, Gtk:Widget *w (check null type), int length) - { - ... - } - -.fi -or -.nf - - signal last NONE(NONE) void foo(self); - -.fi -.PP -If you don't want the wrapper that emits the signal to be public, you can -include the keyword "private" after the "signal" keyword. This will make -the wrapper a normal private method. You can also make a protected wrapper -by using "protected" instead of "private". -.PP -If you don't define a "first" or a "last", the default will be taken as -"last". -.PP -You can also add additional flags. You do this just like with the argument -flags, although this is probably very rare. These are the GTK_RUN_* flags, -and you can add them without the GTK_RUN_ prefix into a parenthesis, just -after the "signal" keyword. By default all public signals are GTK_RUN_ACTION. -.PP -Since 1.0.6, gob creates wrapper signal macros for signal connection -typesafety, at least on gnu compilers. These macros are named -_SIGNAL_(func), where func is the function pointer. This -pointer must be of the correct type, or you will get an initialization from -wrong pointer type warning. This macro, much like the argument macros, wraps -both the name and the function pointer parameters. For example to connect a -signal "changed" to a function "foo", you would do: -.nf - - gtk_signal_connect (GTK_OBJECT (object), - MY_OBJECT_SIGNAL_CHANGED (foo), - NULL); - -.fi -.PP -Override methods: -.PP -If you need to override some method (a signal or a virtual method -of some class in the parent tree of the new object), you can define and -override method. After the "override" keyword, you should put the -typename of the class you are overriding a method from. Other then that -it is the same as for other methods. The "self" pointer in this case -should be the type of the method you are overriding so that you don't -get warnings during compilation. Also to call the method of the parent -class, you can use the PARENT_HANDLER macro with your arguments. Example: -.nf - - override (Gtk:Container) void - add (Gtk:Container *self (check null type), Gtk:Widget *wid (check null type)) - { - /* some code here */ - PARENT_HANDLER(self, wid); - } - -.fi -If the function has a return value, then PARENT_HANDLER is an expression that -you can use. It will return whatever the parent handler returned, or the -"onerror" expression if there was no parent handler. -.PP -Method names: -.PP -Inside the code, aliases are set for the methods, so that you don't -have to type the class name before each call, just the name of the method. -Example: -.nf - - private int - foo(self) - { - return self->len; - } - - private int - bar(self,int i) - { - return foo(self) + i; - } - -.fi -.PP -Underscore removal (0.93.5+): -.PP -Sometimes this causes conflicts with other libraries. For example a library -might have already used the identifier foo. You can prepend an underscore to -the name in the .gob file. This will make the local short alias have an -initial underscore, but it will not change the name of the actual name of the -function. For example: -.nf - class My:Object from Gtk:Object { - public void - _foo(self) { - /* foo body */ - } - public void - bar(self) { - /* short calling convention */ - _foo(self); - /* long calling convention */ - my_object_foo(self); - } - } -.fi -Thus you see that the "_foo" method still generates the method "my_object_foo" -just as "foo" would generate. You can turn off this behavior if you depend -on the old (pre 0.93.5) behavior with the --no-kill-underscores option. This -also means that if both "_foo" and "foo" are defined, it is treated as a -conflict. -.PP -This does not apply to override methods. Override methods are special beasts -and this is not necessary and would make the code behave in weird ways. -.PP -Making new objects: -.PP -You should define a new method which should be a normal public method. Inside -this method, you can use the GET_NEW macro that is defined for you and that -will fetch a new object, so a fairly standard new method would look like: -.nf - - public GtkObject * - new(void) { - GtkObject *ret = GET_NEW; - return GTK_OBJECT (ret); - } - -.fi -.PP -You should not a subtle peculiarity of the GTK+ object system here. If there is any -code inside the GTK_OBJECT macro argument, it will get executed multiple times. This -means that things such as GTK_OBJECT(GET_NEW) would actually create 4 objects, leaking -3 of them. A good rule is to be careful with all macros. -.PP -Self alias casts: -.PP -There are some standard casts defined for you. Instead of using the full -macros inside the .c file, you can use SELF, IS_SELF and SELF_CLASS. Using -these makes it easier to for example change class names around. -.PP -Self alias types: -.PP -Since 0.93.5, there have also been defined the Self and SelfClass types inside -your .c file. These serve the same function as the above, they make it easier -to type and easier to change typenames around which can help a lot during -prototyping stage. However you should note that the Self type should not be -used in function prototypes as one of the arguments or as a return value type. -This is because this is a simple C typedef which is only available inside you -.c file. You can disable both the self casting macros and the self type -aliases by passing --no-self-alias to - -.SH DEALING WITH DIFFERENT GOB VERSIONS -.PP -Defines: -.PP -In your generated C file, you can use the defines GOB_VERSION_MAJOR -GOB_VERSION_MINOR and GOB_VERSION_PATCHLEVEL if you wish to for example -use a feature that is only available in some newer gob version. Note however -that you can only use these defines in the C code portions of your .gob file, -and #ifdef's cannot span multiple functions. Check the BUGS section -for more on using the C preprocessor and gob. Also note that these -have only been available since the 0.92.1 version of gob. -.PP -Minimum version requires: -.PP -You can also make your .gob file require at least certain version of gob. You -do this by putting 'requires x.y.z' (where x.y.z is the version number) outside -of any C block, comment or class, usually you should make this the first line -in the file or close to the top. If gob finds this and the version of gob used -to compile the code is lower then that listed in the require, gob will generate -an error and exit. For example to require that gob version 0.92.1 or higher -be used to compile a file, put this at the top of that file: -.nf - - requires 0.92.1 - -.fi -It should be noted however that this feature was not added until 0.92.1, and -so if the file gets compiled by a lower version, gob would generate a -syntax error. Thus by putting in a requires line, you are implicitly -requiring at least 0.92.1. - -.SH C++ MODE -.PP -There is a C++ mode so that gob creates C++ compiler friendly files. You need -to use the --for-cpp argument to gob. This will make the generated file have -a .cc instead of a .c extension, and several things will be adjusted to -make it all work for a C++ compiler. One thing that will be missing is an -alias to the new method, as that clashes with C++, so instead you'll have to -use the full name of the method inside your code. Also note that gob does -not use any C++ features, this option will just make the generated code -compile with a C++ compiler. - -.SH OVERRIDING THE GET_TYPE METHOD -.PP -The get_type is not really a method, but a function which initializes your -object. Recently objects appeared which require you to make a custom -get_type function (BonoboXObject currently). So in 1.0.7 it is now possible -to override this function. To do so, just define a new public method called -get_type, with no arguments. Example: -.nf - - public GtkType - get_type (void) - { - /* code goes here */ - return some_type; - } - -.fi - -.SH IDENTIFIER CONFLICTS -.PP -Gob will need to define some local variables and functions in the generated -files, so you need to take some precaution not to conflict with these. The -general rule of thumb is that all of these start with three underscores. There -is one, "parent_class" which doesn't because it's intended for use in your -code. For virtuals or signals, you cannot use the identifier __parent__ -which is used for the parent of the object. You should actually never access -__parent__ either as it not guaranteed that it will stay named this way. -Data members cannot be named __parent__ nor _priv. For methods, you cannot -use the identifiers "init" or "class_init" unless you mean the constructor -methods. You shouldn't generally use 3 underscores even in override method -argument lists and virtual and signal method names as it might confuse the -PARENT_HANDLER macro. In fact avoiding all names with three underscores is -the best policy when working with gob. -.PP -Also note that starting with version 0.93.5, method names that start with a -an underscore are equivalent to the names without the initial underscore. This -is done to avoid conflicts with the aliases. Thus you can define the method -as "_name", if "name" happens to be some standard library function. This is -the same as defining it as "name" except that the local alias will be "_name" -rather then "name". -.PP -There are a couple of defines which you shouldn't be redefining in the code -or other headers. These are SELF, IS_SELF, SELF_CLASS, ARG, VAR, -PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR and -GOB_VERSION_PATCHLEVEL. -.PP -As for types, there are Self and SelfClass types which are only defined in your -source files. Their generation (just like the generation of the SELF macros) -can be turned off, see command line options. - -.SH USING GTK-DOC STYLE INLINE DOCUMENTATION -.PP -If you want to use gtk-doc style inline documentation for your objects, you -can do one of two things. First, you could include the inline documentation -comments in your %{ %} section which will then be put verbatim into the -output source file. This is the way you should use for functions you define -outside of the class. -.PP -For class methods, you should use a gtk+ style comment, however it can be -indented any number of tabs or spaces and you can use the short method name -without the type prefix. Gob will automatically try to extract these and -translate to full names and put them in the output source file. An example -would be: -.nf - - class Gtk:Button:Example from Gtk:Button { - /** - * new: - * - * Makes a new #GtkButtonExample widget - * - * Returns: a new widget - **/ - public - GtkWidget * - new(void) - { - return GTK_WIDGET(GET_NEW); - } - } - -.fi -If the function you are documenting is a signal or a virtual then it will -be documenting the wrapper that starts that virtual function or emits -that signal. - -.SH DEALING WITH CIRCULAR HEADERS -.PP -Sometimes you may need to use an object of type MyObjectA in the MyObjectB -class and vice versa. Obviously you can't include headers for both. So you -need to just declare the typedef in the header of A for B, and the other way -around as well. The headers generated since v0.92.2 include a protecting -define before it declares the typedef. This define is the -__TYPEDEF___. So inside my-object-a.h there will be -this: -.nf - - #ifndef __TYPEDEF_MY_OBJECT_A__ - #define __TYPEDEF_MY_OBJECT_A__ - typedef struct _MyObjectA MyObjectA; - #endif - -.fi -Now instead of including my-object-a.h in the header section of -my-object-b.gob, just copy the above code there and you're set for using -MyObjectA as a type in the method parameters and public types. -.PP -Another way to get out of this problem is if you can use those types only -in the private members, in which case they won't be in the generated public -header. - -.SH BUILDING WITH MAKE -.PP -If you are using normal makefiles, what you need to do is to add a generic -rule for .gob files. So you would include the following in the Makefile -and then just use the .c and .h files as usual (make sure the space -before the 'gob' is a tab, not spaces): -.nf - - %.c %.h %-private.h: %.gob - gob $< - -.fi - -.SH BUILDING WITH AUTOCONF and AUTOMAKE -.PP -This is a little bit more involved. Basically the first thing to do is to -check for GOB in your configure.in file. You can use the supplied m4 macro -which will also check the version of gob. Basically you include this: -.nf - - GOB_CHECK(0.93.4) - -.fi -This will replace @GOB@ in your makefiles with the full path of gob. Thus -when adding the generic rule to your Makefile.am file, it should look like: -.nf - - %.c %.h %-private.h: %.gob - @GOB@ $< - -.fi -.PP -For Makefile.am you have to set up a couple more things. First you have to -include the generated .c and .h files into BUILT_SOURCES variable. You -have to include both the .gob and the .c and .h files in the SOURCES for your -program. - -.SH DEBUGGING -.PP -GOB does several things to make debugging the code easier. First it adds -preprocessor commands into the output c file that point to the correct places -in your .gob input file. However sometimes there might be some bigger -confusion and this is just not helpful. In this case you will probably want -to have gcc point you directly at the generated files. For this use -the --no-lines command line option. You should also note that these commands -are not generated for the public header file at all. If there is an error which -points you to the public header file, make sure you fix this error in the .gob -file, otherwise your changes will not have any effect after gob recompiles the -sources again. -.PP -Sometimes you might want to know which method you are in for some debugging -output. GOB will define __GOB_FUNCTION__ macro, which is just a string constant -with a pretty name of the method. - -.SH BUGS -.PP -The lexer does not actually parse the C code, so I'm sure that some corner -cases or maybe even some not so corner cases of C syntax might confuse gob -completely. If you find any, send me the source that makes it go gaga and I'll -try to make the lexer try to handle it properly, but no promises. -.PP -Another thing is that gob ignores preprocessor macros. Since gob counts -braces, the following code won't work: -.nf - - #ifdef SOME_DEFINE - if(foo) { - #else - if(bar) { - #endif - blah(); - } - -.fi -To make this work, you'd have to do this: -.nf - - #ifdef SOME_DEFINE - if(foo) - #else - if(bar) - #endif - { - blah(); - } - -.fi -There is no real good way we can handle this without parsing C code, so we -probably never will. In the future, I might add #if 0 as a comment but -that's about as far as I can really take it and even that is problematic. -Basically, if you use gob, just don't use the C preprocessor too extensively. -.PP -Comments will not get through to the generated files unless inside C code. -This makes using something like gtk-doc harder. However I'm planning to -fix this somehow. -.PP -The short name aliases are actually implemented as pointers to functions. Thus -if you want to get the pointer of a function using the short name alias you -can't use the '&'. Thus: -.nf - - void (*foo)(Self *); - - /* this will NOT work */ - foo = &short_name; - - /* this will work */ - foo = short_name; - - /* Both of these will work */ - foo = &my_class_long_name; - foo = my_class_long_name; - -.fi - -.SH AUTHOR -.PP -George Lebl