X-Git-Url: https://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/072bb12e618b26cce359784aa56f9a2b70e1ce52..5cfe51ee2287165feb0cf006901bbbc2b961f3b8:/doc/gob.1.in diff --git a/doc/gob.1.in b/doc/gob.1.in index 9e1ce35..644be0b 100644 --- a/doc/gob.1.in +++ b/doc/gob.1.in @@ -77,6 +77,11 @@ 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 @@ -377,18 +382,18 @@ 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); + 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); + gtk_object_get (GTK_OBJECT (object), + MY_OBJECT_GET_ARG_HEIGHT (&height), + NULL); .fi Note however that the type safety only works completely on GNU C compilers. @@ -439,7 +444,7 @@ is just like private char * foo; argument POINTER (type char *) foo get { - ARG = self->_priv->foo; + ARG = g_strdup(self->_priv->foo); } set { g_free(self->_priv->foo); self->_priv->foo = g_strdup(ARG); @@ -461,21 +466,33 @@ is just like get { ARG = self->foo; } set { - if(self->foo) + if(ARG != NULL) + gtk_object_ref(ARG); + if(self->foo != NULL) 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. -Also you should notice that when the get is used, only a pointer is always -returned for both objectlink and strinklink. So you should treat the returned -value with care and never free it (and notice that it will only be around -until you set the argument to something else or destroy the object). +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 +You can also automatically export get and set methods for each of the arguments +by appending '(export)' flag before the get and set statements. For example: +.nf + + public int foo; + argument INT (type int) foo (export) + get { ARG = self->foo; } + set { self->foo = ARG; }; + +.fi +Will export public methods get_foo(self) and set_foo(self, int foo) for you +automatically. Note that this behaviour is new in 1.0.10. .PP Methods: .PP @@ -650,6 +667,25 @@ 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 +Note that if you are compiling with GTK+2, this will not work. You must +only use this with gtk_signal_connect_full. Also the above macros don't +exist in gob2, where typesafe signals are handled another way. +.PP Override methods: .PP If you need to override some method (a signal or a virtual method @@ -735,13 +771,17 @@ will fetch a new object, so a fairly standard new method would look like: public GtkObject * new(void) { - GtkObject *ret; - ret = GTK_OBJECT (GET_NEW); - return ret; + 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 @@ -801,6 +841,64 @@ 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, see next section for direct +BonoboXObject support). 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 DIRECT BonoboXObject SUPPORT +.PP +If you want to build a BonoboXObject class gob has direct support for these +classes since 1.0.9. Just create a new object that derives from +Bonobo:X:Object. Then use a "BonoboX" class flag with the interface name as an +argument. The interface name should be as you would type it in C, that is with +underscores as namespace separators. Then you add the methods (using exact +same names as in the idl file) and prepend those methods with a BonoboX +keyword. For example imagine you have an interface GNOME/Foo/SomeInterface, +with a method fooBar that takes a single string: +.nf + + class Foo:Some:Interface from Bonobo:X:Object + (BonoboX GNOME_Foo_SomeInterface) { + + BonoboX + private void + fooBar (PortableServer_Servant servant, + const CORBA_char *string, + CORBA_Environment *ev) + { + Self *self = SELF (bonobo_object_from_servant (servant)); + + /* your code here */ + } + + /* rest of class */ + } + +.fi +Note that the implementation method can be private, in fact that's probably +a good idea to do. It won't work to make this a signal, it can however +be a virtual. Note that the method prototype must match the one from the +interface header file, or you will get a bad assignment warning. You should +check the header file generated by orbit-idl and see the epv structure +for the correct prototypes if you can't figure them out from the idl itself. +Also note that the first argument is not "self", but the servant and you must +use bonobo_object_from_servant function to get the actual object pointer. + .SH IDENTIFIER CONFLICTS .PP Gob will need to define some local variables and functions in the generated @@ -931,6 +1029,23 @@ 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 @@ -970,8 +1085,7 @@ 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. +This is not the case for gtk-doc style comments which are supported. .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