X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/6d0fe9d5f8c513045bf064ea256c822beac19037..2255b3d84eeb947d4c065332f16e410ae4704c63:/doc/gob.1.in diff --git a/doc/gob.1.in b/doc/gob.1.in index fa5dd9b..1f88d7c 100644 --- a/doc/gob.1.in +++ b/doc/gob.1.in @@ -10,8 +10,8 @@ GOB \- The GTK+ Object Builder .SH SYNOPSIS .PP -.B gob [-?] [-h] [-w] [--exit-on-warn] [--no-exit-on-warn] [--for-cpp] -[--no-touch-headers] file +.B gob [-?] [-h] [--help] [--version] [-w] [--exit-on-warn] +[--no-exit-on-warn] [--for-cpp] [--no-touch-headers] file .SH DESCRIPTION .PP GTK+ Object Builder is a simple preprocessor for easily creating @@ -24,8 +24,13 @@ is in spirit similar to things like lex or yacc. .B -? .TP .B -h +.TP +.B --help Display a simple help screen. .TP +.B --version +Display version information (note, --version was not added until 0.92.0) +.TP .B -w .TP .B --exit-on-warn @@ -40,7 +45,8 @@ Generate C++ code. .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. +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. @@ -141,20 +147,24 @@ For example: .PP Data members: .PP -There are three types of data members. Two of them are normal -data numbers, and one is a virtual one, usually linked to a normal public -data member. The two normal data members are public or private. They are -basically just copied into the object directly. There is only one +There are four types of data members. Three of them are normal +data numbers, and one is a virtual one, usually linked to a normal +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 datamembers are accessed normally as members of the object struct. -Example where 'i' is as above a public data member: +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; @@ -162,21 +172,24 @@ Example where 'i' is as above a public data member: .fi .PP The private data members are defined in a structure which is only available -inside the .c file. You must access them using the structure _priv. Example +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 -Note that the _priv structure is defined in the \fB-private.h\fR. +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 if you explicitly also include the main -header file. In case you use the \fB--no-private-header\fR option, no +header file. +.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 -The third type is an argument type. It is a named datamember which +The fourth type is an argument type. It is a named datamember 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 @@ -202,17 +215,27 @@ without the GTK_ARG_ prefix. For example: .fi This makes the argument settable even before the object is constructed, so -that people can pass it to gtk_object_new function. +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 Methods: .PP -There is a whole array of possible methods. The two normal, -"familiar" method types are private and public. Public are defined as -normal functions with a prototype in the header file. Private methods +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. You can also +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 Argument lists: .PP @@ -261,6 +284,9 @@ output, they just delimit the string. For example: } .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 Constructor methods: .PP @@ -300,8 +326,9 @@ so that one can override the method in derived methods. They can be empty 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" +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 @@ -335,8 +362,9 @@ or .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. +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". @@ -450,6 +478,10 @@ 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. .SH AUTHOR .PP