Release 0.92.0

[gob-dx.git] / doc / gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index fa5dd9b084ffed44ca78e291d3aff1465d32177c..1f88d7c446359257cf15288105ef17212c270141 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -10,8 +10,8 @@
 GOB \- The GTK+ Object Builder
 .SH SYNOPSIS
 .PP
 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
 .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
 .B -?
 .TP
 .B -h

+.TP
+.B --help

 Display a simple help screen.
 .TP
 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
 .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),
 .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<basename>-private.h\fR file, even if it would be empty.
 .TP
 .B --always-private-header
 Always create a \fB<basename>-private.h\fR file, even if it would be empty.


@@ -141,20 +147,24 @@ For example:
 .PP
 Data members:
 .PP
 .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;
 identifier allowed per typename unlike in normal C.  Example:
 .nf
 
   public int i;
   private GtkWidget *h;

+  protected long k;

 
 .fi
 .PP
 
 .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;
 .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
 .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
 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<basename>-private.h\fR.
+The _priv structure is defined in the \fB<basename>-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
 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
 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
 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
 
 .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
 .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
 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.
 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
 .PP
 Argument lists:
 .PP


@@ -261,6 +284,9 @@ output, they just delimit the string.  For example:
   }
 
 .fi
   }
 
 .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
 .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
 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.
 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
 .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
 .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".
 .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.
 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
 
 .SH AUTHOR
 .PP