X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/a611f21fab136f64bbf979bd62b2fc6ecb62933c..2255b3d84eeb947d4c065332f16e410ae4704c63:/doc/gob.1.in diff --git a/doc/gob.1.in b/doc/gob.1.in index 4268580..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,8 +45,19 @@ 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. +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 datamembers, +define the private data structure at the point in the .c source where +the class definition begins. This option implicitly negates +--always-private-header .SH TYPENAMES .PP @@ -58,8 +74,13 @@ types. .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 gtk-new-button.c and gtk-new-button.h. -The header file is created to be human readable and to be used as a +"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 @@ -89,6 +110,23 @@ For example: .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: @@ -109,23 +147,49 @@ 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 -The private members are not currently protected from outside use, -they are just marked by a comment in the header file, this will most likely -be somehow solved in some future version. +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 third type is an argument type. It is a named datamember which +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 if you explicitly also include the main +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 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 @@ -150,20 +214,32 @@ without the GTK_ARG_ prefix. For example: 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 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 -define init and init_class methods with a special definition if you want +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 -For all but the init and init_class methods, you use the +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 @@ -200,7 +276,7 @@ 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 +output, they just delimit the string. For example: .nf public void * get_something(self, int i (check >= 0)) onerror NULL { @@ -208,6 +284,39 @@ 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 +There are two methods that handle the cosntruction 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(object) { + /* initialize the object here */ + object->a = 9; + object->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 @@ -217,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 @@ -252,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". @@ -276,7 +387,11 @@ class, you can use the PARENT_HANDLER macro with your arguments. Example: /* 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 Calling methods: .PP @@ -306,7 +421,7 @@ 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 GtkWidget * + public GtkObject * new(void) { GtkObject *ret; ret = GTK_OBJECT (GET_NEW); @@ -328,10 +443,6 @@ compile with a C++ compiler. .SH BUGS .PP -The generated header file is included as the first file in the .c file, no -matter what. This means that you will have to put things that need to be -included before that, into an %h{ } section. -.PP Also 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 @@ -367,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