gob2 man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

GOB2(1)								       GOB2(1)

NAME
       GOB2 - The GObject Builder

SYNOPSIS
       gob2 [ option ] ...  file

DESCRIPTION
       GObject	Builder	 is  a simple preprocessor for easily creating GObject
       objects.	 It does not parse any C code and ignores any C errors.	 It is
       in  spirit  similar  to	things like lex or yacc.  In some ways it also
       resembles java.	But it is really just a simple preprocessor for creat‐
       ing GObjects for use in C or C++ and it is not a programming language.

OPTIONS
       -? -h --help
	      Display a simple help screen.

       --version
	      Display version information

       -w --exit-on-warn
	      Exit with an error code even when you encounter a warning.

       --no-exit-on-warn
	      Exit  with an error only on errors, not on warnings, this is the
	      default.

       --for-cpp
	      Generate C++ code.

       --no-extern-c
	      Never add the extern "C" to the header.

       --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)

       --no-touch
	      Don´t  touch  output  files  unless they really changed (implies
	      --no-touch-headers).  Be careful with automake, see section PRE‐
	      VENTING SPURIOUS BUILDS.

       --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.  Pri‐
	      vate header is still touched even if unchanged however.

       --always-private-header
	      Always create a <basename>-private.h file, even if it  would  be
	      empty.

       --ondemand-private-header
	      Create the private header only if it would have something in it,
	      that is, if there are some private  data	members	 or  protected
	      methods.	This is the default.

       --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.

       --m4   Preprocess source with m4. Following args will be passed to m4.

       --m4-dir
	      Print directory that will be searched for m4 files.

       -n --no-write
	      Do  not  write  any output files, just check syntax of the input
	      file.

       --no-lines
	      Do not print out the ´#line´ statements into the output.	Useful
	      for debugging the auto-generated generated code.

       --no-self-alias
	      Do  not create the Self and SelfClass type aliases and the SELF,
	      IS_SELF and SELF_CLASS macros.

       --no-kill-underscores
	      Do not remove the initial underscore from method names.

       --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 with‐
	      out breaking binary compatibility.

       -o --output-dir
	      The directory into which output should be placed.

       --file-sep[=c]
	      Replace  default `-´ file name separator.	 If no separator char‐
	      acter is given then none is used.	 Only  one  character  can  be
	      used.

TYPENAMES
       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.

OUTPUT FILES
       The filenames are created from the typename.  The words	are  separated
       by  `-´	(this  can be changed with --file-sep option) 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.	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 <base‐
       name>-private.h (for the example above it would be  gtk-new-button-pri‐
       vate.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  cre‐
       ated  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.

INCLUDING NORMAL C CODE IN THE OUTPUT FILES
       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 sections 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 ´pri‐
       vateheader´ 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.
       Finally,	 ´afterdecls´  includes	 code between the declarations and the
       method implementations, but note	 that  ´afterdecls´  requires  version
       2.0.16.	For example:

	 %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 */
	 %}

	 %afterdecls{
	       /* between the declarations and the method implementations */
	       /* Requires gob version 2.0.16 */
	 %}

	 %{
	       /* will be included in the C file */
	       void somefunc(int i)
	       {
		     /* some code */
	       }
	 %}

INCLUDE FILES
       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.

       If you made any data members private, gob will  also  create  a	source
       file  that  will	 be  called  <basename>-private.h.  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 automati‐
       cally includes the public header file, and thus the public header  file
       will be indirectly included at the very top of the file.

THE CLASS HEADER
       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 <new type> from <parent type> { <class code>
       }".  For example:

	 class Gtk:New:Button from Gtk:Button {
	      <class code>
	 }

       To  make	 an  abstract  class  (to   pass   G_TYPE_FLAG_ABSTRACT)   add
       ´(abstract)´  before  the curly braces above.  This works since version
       2.0.13.

DATA MEMBERS
       There are five types of data members.  Three of them  are  normal  data
       members,	 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.  Pub‐
       lic 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 identi‐
       fier allowed per typename unlike in normal C.  Example:

	 public int i;
	 private GtkWidget *h;
	 protected long k;

       Public and protected data members are accessed normally as  members  of
       the object struct.  Example where ´i´ is as above a public data member:

	 object->i = 1;

       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):

	 object->_priv->h = NULL;

       The _priv structure is defined in the <basename>-private.h.  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 func‐
       tionality of an object in a separate .c file.  Or if a  derived	object
       needs to access the protected methods.

       In  case you use the --no-private-header option, no private header file
       is created and you can only access the _priv pointer  below  the	 class
       definition in the .gob file.

       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.

       Classwide data members:

       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:

	 classwide int foo;

       To  access  the	member	you  can  use  the  SELF_GET_CLASS  macro  (or
       YOUR_OBJECT_NAME_GET_CLASS) to get at the class.	  Thus	the  following
       would work:

	 SELF_GET_CLASS(object)->foo = 20;

       Automatic Initialization:

       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".

	 public int foo = -1;
	 private char *bar = {g_strdup("hello")};

       Automatic Destruction:

       Most  data  stored as pointers needs to have a function called when the
       object is finalized to either free the data.  Gob will let you define a
       function	 to  be	 called	 on the data the object is finalized.  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:

	 public char *foo = {g_strdup("bar")}
		 destroywith g_free;

       Note  that  the	function name you give must be a real function and not
       macro.  Also note that this is always called in the  "finalize"	method
       of  GObject.   It  is  always called after any user defined body of the
       finalize handler.

       Sometimes you may want to run arbitrary	code  on  destruction.	 While
       this  can be perfectly well done in the finalize 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  "finalize"
       method  of  GObject.   This can be done with the "destroy" keyword fol‐
       lowed by arbitrary code in curly braces.	  Inside  this	code  a	 macro
       called  VAR will be define which refers to your variable.  So for exam‐
       ple destroying a GString can be either done with a  helper  routine  or
       the following code:

	 public GString *string = {g_string_new(NULL)}
		 destroy {
		      if(VAR) g_string_free(VAR, TRUE);
	      };

       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.

       The data is zeroed out after being destroyed.  This is to  make	debug‐
       ging  easier in case your code might try to access an already finalized
       object.	In case you have overridden the	 finalize  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 destruc‐
       tors for different data members, you will have to do this in  your  own
       finalize override function.

       Automatic Unreffing:

       This is very much like the automatic destruction, but is instead run in
       the dispose method (it is among other places called from the  "destroy"
       method  of  GtkObject).	 All  data  and other objects that you need to
       unref should be done here, and not at finalize time.  The semantics are
       otherwise  the  same  as	 for the "destroywith" and "destroy" keywords,
       except that you use "unrefwith" and "unref".

	 public G:Object *foo = NULL
		 unrefwith g_object_unref;
	 public G:Object *bar = NULL
		 unref {
		 g_object_unref (VAR);
	      };

GOBJECT PROPERTIES
       The fourth type of a data member a property type.  It is a  named  data
       member  which  is  one  of the features of the GObject system.  It just
       defines a way to get and set some data, but you have to	take  care  of
       storing	that  data  somewhere.	 So it is normal to also have a normal
       private (or public) data member where you store	the  real  data.   You
       normally 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 argu‐
       ment.   Inside  them you can use the define VAL to which you assign the
       data or get the data.  You should treat this  VAL  as  a	 GValue	 which
       stores  the  data of the correct type.  You can also use the identifier
       "self" as pointer to the object instance.  The type is defined  as  one
       of  the	GObject type enums, but without the G_TYPE_ prefix.  There are
       also some attributes of a property which you can set.  For example  the
       following is a definition of an integer property ´height´ which will be
       synchronized with a private  integer  data  member  also	 of  the  name
       ´height´.

	 private int height;
	 property INT height
		(nick = _("Short nickname"),
		 blurb = _("Long description"),
		 minimum = 10,
		 maximum = 200,
		 default_value = 100)
	       set { self->_priv->height = g_value_get_int (VAL); }
	       get { g_value_set_int (VAL, self->_priv->height); };

       The  attributes are really optional though you should at least set some
       of them.	 All property types have a ´nick´ and a ´blurb´ attribute  and
       you  should set those accordingly.  This will make runtime querying the
       object nicer as things such as gui editors and class  browsers  can  be
       more  verbose  about  the  class itself.	 You can use the ´_("string")´
       notation instead of just "string", and that will mark  the  string  for
       translation.

       Almost  all  types also have a ´default_value´ attribute which sets the
       initial value of this property (on object initialization, the set  han‐
       dler  will  be  run automatically with this value).  This value will be
       overriden if the user sets a value of this  property  on	 the  call  to
       g_object_new.

       All  the	 numeric  types	 (including CHAR) have ´minimum´ and ´maximum´
       attributes which can restrict the range.	 If you do not	specify	 these
       the range will be the full range that the data type can handle.

       Types  such  as	UNICHAR	 and BOOLEAN only have the ´nick´, ´blurb´ and
       ´default_value´ attributes.

       The ENUM type has an ´enum_type´ attribute which is the exact  type  of
       the  enum.  This is so that the property knows which exact type you can
       set, rather then just knowing it is an enum.  You should always	create
       an  enum	 type  specific	 for  the enum itself (see section on the enum
       types)

       Similarly FLAGS type has a ´flags_type´ which again you should  set  to
       the specific type of this flags data member.

       There  is  a  STRING  type  which  has  only  the extra ´default_value´
       attribute.

       The OBJECT type is one of the types that doesn´t have a ´default_value´
       and  it	only  has  an ´object_type´ attribute (in addition to nick and
       blurb of course) that is the  exact  object  type  that	this  property
       accepts.	  The  object_type  should  be	as a type, that is for example
       ´Gtk:Button´.

       There is a BOXED type which is a pointer which has a boxed type defined
       (such  that  GObject knows how to copy and destroy this pointer).  Here
       you will need to specify the ´boxed_type´ attribute with	 the  specific
       type of the boxed pointer.

       There  is  also	a  POINTER type, which has only the ´nick´ and ´blurb´
       attributes.  This is for storing arbitrary  pointers.   You  should  be
       careful	with  this one, as GObject knows nothing about the data stored
       at this pointer.	 It is somewhat like a ´void *´ type.

       There is also the PARAM type for storing parameters with a ´param_type´
       attribute.

       You  should  notice  that  this	list  is  pretty much like the list of
       g_param_spec_* functions from gobject/gparamspecs.h, and the attributes
       are  like  the  arguments  of those functions.  Note however that value
       array is NOT supported yet.

       You can also specify extra flags, such as CONSTRUCT  or	CONSTRUCT_ONLY
       using  the  ´flags´ attribute.  You can specify multiple flags by oring
       them together with ´|´.	These flags correspond to the GParamFlags enu‐
       meration	 except do not include the G_PARAM_ prefix.  So for example to
       define an enumeration property, which is a CONSTRUCT_ONLY property,  we
       could do the following:

	 private SomeEnumerationType foo;
	 property ENUM foo
		(nick = _("Short nickname"),
		 blurb = _("Long description"),
		 enum_type = Some:Enumeration:Type
		 default_value = SOME_ENUMERATION_VALUE,
		 flags = CONSTRUCT_ONLY,
		 link);

       The above example also gives an example of automatic linking to a stan‐
       dard data memember.  By including the attribute ´link´ a	 get  and  set
       handlers	 will  be  automatically  added without having to type them by
       hand.  This is useful for a vast majority  data	types  that  are  just
       linked  to  some	 standard  data	 member and do not need to do anything
       extra on get or set.

       Another extra feature of properties is the possibility of automatically
       exporing	 methods  to get and set the property.	That is without having
       to use g_object_set and g_object_get.  This is achieved	by  adding  an
       ´export´ attribute to the list of property attributes.

       If  you do not define a set or get handler, the property will automati‐
       cally be only readable or writable as appropriate.

       Gob2 also creates macros which can be used  for	type  safe  access  to
       properties  through  g_object_set  and  g_object_get.   The  macros are
       called  <type>_PROP_<argument  name>(x)	and  <type>_GET_PROP_<argument
       name>(x).   They define both the string and the value part of the argu‐
       ment.  So for setting an argument of height, one would use (for	object
       type My:Object):

	 g_object_set (G_OBJECT (object),
		 MY_OBJECT_PROP_HEIGHT (7),
		 NULL);

       And for getting, you would use:

	 int height;
	 g_object_get (G_OBJECT (object),
		 MY_OBJECT_GET_PROP_HEIGHT (&height),
		 NULL);

       Note  however  that the type safety only works completely on GNU C com‐
       pilers.	The code will compile on other compilers but with minimal type
       safety.	For complete type safety it is useful to use the get/set meth‐
       ods that are defined by using the ´export´ attribute.

       To get bettery type safety on some of the property types, you can spec‐
       ify the ´type´ attribute which will add casts where appropriate in code
       dealing with this property.  This is especially useful for POINTER  and
       OBJECT types.  But even for others.

       You  can also override properties from parent objects (that is override
       their implementation, not their attributes).  Do	 this  by  adding  the
       special	´override´  attribute.	For example if the parent object had a
       ´height´ property then you could override it by

	 private int height;
	 property INT height
		(override)
	       set { self->_priv->height = g_value_get_int (VAL); }
	       get { g_value_set_int (VAL, self->_priv->height); };

       Overriding is supported since gob 2.0.10.

METHODS
       There is a whole array of possible methods.  The three normal,  "famil‐
       iar"  method  types  are	 private,  protected  and  public.  Public are
       defined as normal functions with a prototype in the header file.	  Pro‐
       tected  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	 meth‐
       ods.   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  con‐
       structors  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 pub‐
       lic, private or protected methods, however it is	 acceptable  for  non-
       void virtual, signal and override methods.

       Function argument lists:

       For all but the init and class_init methods, you use the following syn‐
       tax 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 ´:´
       <type> <argument id>
       or
       <type> <argument id> (check <list of checks>)

       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, "<test> <number>" which tests
       numeric	arguments  for	being  a  certain  value.   The	 test can be a
       <,>,<=,>= != or ==.  Example:

	 public int
	 foo (self,
	      int h (check > 0 < 11),
	      Gtk:Widget *w (check null type))

       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.

       Function attributes:

       For method that aren't virtual, signal or override methods, and	aren't
       init  or	 class_init,  GLib  function  attribute	 macros G_GNUC_PRINTF,
       G_GNUC_SCANF, and G_GNUC_FORMAT can optionally be  included  after  the
       argument	 list.	 Simply	 include  an  ´attr´ keyword and the C code to
       include in the file.  You have to include braces	 and  anything	inside
       the braces will be printed into the header file after the function dec‐
       laration and before the trailing semicolon.  The braces themselves  are
       not printed.  For example:

	 public void
	 print (self, const char *format (check null), ...)
	   attr {G_GNUC_PRINTF(2, 3)}

       This  will produce a prototype which will generate a warning at compile
       time if the contents of the format argument (argument number 2)	aren't
       consistent  with	 the types and number of the subsequent variadic argu‐
       ments (the first of which is argument number 3).	 Only one ´attr´  key‐
       word  per  method  is  allowed.	If you have more than one attribute to
       include, you should put them all within the braces.  Note that function
       attributes were aded in version 2.0.16.

       Error return:

       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  any	 optional function attribute macros, 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:

	 public void * get_something (self, int i (check >= 0)) onerror NULL {
	      ...
	 }

       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.

       Default return:

       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.  GOB2
       will normally have  the	wrappers  return  whatever  you	 specify  with
       onerror or ´0´ if you haven´t specified anything.  You can also specify
       a default return value with the keyword ´defreturn´.  It´s use is iden‐
       tical  to  the use of onerror, and you can in fact use both at the same
       time.  Example

	 virtual int get_some_int (self) onerror -1 defreturn 10 ;

       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.

       Constructor methods:

       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:

	 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;
	 }

       The class_init function is very rarely needed  as  all  standard	 class
       initialization  is taken care of for you by gob itself.	The init func‐
       tion 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.

       Constructor, dispose, finalize methods:

       Since 2.0.16, you can also easily add code to the object's constructor,
       dispose, and finalize methods.  See GObject documentation on how	 these
       are run.	 The code you add will be run before calling the parents func‐
       tion for dispose and finalize, and after the parent function  for  con‐
       structor.  The syntax is just like init and class_init.	For example:

	 constructor (self) {
	    /* constructor method */
	 }

	 dispose (self) {
	    /* dispose method */
	 }

	 finalize (self) {
	    /* finalize method */
	 }

       You  can	 also  just  override those methods as usual, but the above is
       much easier and nearly as flexible.

       Virtual methods:

       Virtual methods are basically pointers in the class structure, so  that
       one  can	 override the method in derived methods.  That is to implement
       the method in a derived class, you must then  use  an  override	method
       (more  on  those	 later).  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 lit‐
       tle 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.

       Signals:

       Signals are methods to which the user can bind other handlers and over‐
       ride  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  GObject  enum	 types
       (again  without	the  G_TYPE_  prefix).	For that you define the return
       types and the types of arguments after the "self" pointer (not  includ‐
       ing  the	 "self" pointer).  You put it in the following syntax "<return
       type> (<list of arguments>)".  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:

	 signal first INT (POINTER, INT)
	 int do_something (self, Gtk:Widget *w (check null type), int length)
	 {
	      ...
	 }

       or

	 signal last NONE (NONE) void foo (self);

       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".

       If you don´t define a "first" or a "last", the default will be taken as
       "last".

       You can also add additional flags.  You do  this	 just  like  with  the
       argument	 flags,	 although  this	 is probably very rare.	 These are the
       G_SIGNAL_* flags, and you can add them  without	the  G_SIGNAL_	prefix
       into  a	parenthesis,  just after the "signal" keyword.	By default all
       public signals are G_SIGNAL_ACTION.

       Also gob2 creates a wrapper  macros  for	 typesafe  signal  connection.
       That  is you will be warned by the compiler if you pass a callback that
       is not the correct prototype.  This will again only warn	 you  on  gcc,
       but  it	will  compile without warning on another compiler.  So as with
       all the typesafety hacks in gob, it is  better  to  test	 your  objects
       under  gcc  to  get any warnings even if you are using a different com‐
       piler in the end.

       The methods that are created for you are:

	 <class_name>_connect__<signal_name> (<object>, <callback>, <data>)
	 <class_name>_connect_after__<signal_name> (<object>, <callback>, <data>)
	 <class_name>_connect_data__<signal_name> (<object>, <callback>, <data>,
						   <destroy_notify>, <flags>)

       These three functions correspond to the g_signal_connect, g_signal_con‐
       nect_after  and g_signal_connect_data functions that you would normally
       use, except they are for a specific  signal.   Also  do	note  the  two
       underscores  between  the method name and the signal name.  For example
       to connect the signal "foo" on the object "Test:Object" you would do:

	 test_object_connect__foo (object, callback, data);

       To use BOXED in the signal arguments you need to tell gob which type of
       boxed   argument	  you  want  to	 use.	For  this  you	can  just  add
       BOXED_GTK_TYPE_STRING	instead	    of	   BOXED.      For     example
       BOXED_GTK_TYPE_TREE_ITER	 for  GtkTreeIter.   This  works since version
       2.0.13.

       Override methods:

       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:

	 override (Gtk:Container) void
	 add (Gtk:Container *self (check null type), Gtk:Widget *wid (check null type))
	 {
		 /* some code here */
		 PARENT_HANDLER(self, wid);
	 }

       If the function has a return value, then PARENT_HANDLER is  an  expres‐
       sion  that  you	can  use.   It will return whatever the parent handler
       returned, or the "onerror" expression if there was no parent handler.

       Method names:

       Inside the code, aliases are set for the methods,  so  that  you	 don´t
       have  to	 type the class name before each call, just type self_ instead
       of the name of the class.  So to call a method called blah,  you	 would
       use the name self_blah.	Example:

	 private int
	 foo (self)
	 {
	      return self->len;
	 }

	 private int
	 bar (self, int i)
	 {
	      return self_foo (self) + i;
	 }

MAKING NEW OBJECTS
       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:

	 public GObject *
	 new (void) {
	      GObject *ret = GET_NEW;
	      return G_OBJECT (ret);
	 }

       You should not a subtle peculiarity of the  GObject  system  here.   If
       there  is any code inside the G_OBJECT macro argument, it will get exe‐
       cuted multiple times.  This means that things such as G_OBJECT(GET_NEW)
       would  actually	create	4 objects, leaking 3 of them.  A good rule (as
       with anywhere in C) is to be careful with all macros.

SELF REFERENCES
       Self alias casts:

       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.

       Self alias types:

       There are also 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 prototyp‐
       ing 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  your	.c  file and not in the header files.  You can
       disable both the self casting macros and the self type aliases by pass‐
       ing --no-self-alias to gob.

DEALING WITH DIFFERENT GOB VERSIONS
       Defines:

       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.

       Minimum version requires:

       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 ver‐
       sion 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 gob2 version 2.0.0 or  higher  be  used  to
       compile a file, put this at the top of that file:

	 requires 2.0.0

CREATING NEW ENUM, FLAGS and ERROR TYPES
       You can create new GObject ENUM, FLAGS and GError types for use in your
       classes easily.	Glib includes some utilities for handling these,  how‐
       ever  it may be cleaner to use the below specified way in your classes.
       It also then doesn´t require any Makefile setup.	  Make	sure  this  is
       defined	in  the	 same  section as the class, that is not in any of the
       ´%?{´ ´%}´ sections.

       You use the keywords ´enum´ ´flags´ and ´error´ as you  would  use  the
       ´class´ keyword.	 Then you give a prefix for the values in the enumera‐
       tion.  Then you define a list of values just like  in  C.   For	´enum´
       types  you  can	also specify the values assigned to each string.  Then
       you specify the type in the standard gob	 style	of  specifying	types.
       Here are a few examples of all of these:

	 enum LAME_CLIENT {
	       IS_CONNECTED,
	       NONE = 9,
	       LAST
	 } Test:Enum;

	 flags BUGA_BUGA {
	       ONE,
	       TWO,
	       MANY,
	 } Some:Flags;

	 error TEST_OBJECT_ERROR {
	       BAD_THIS,
	       BAD_THAT
	 } Test:Object:Error;

       This  will for example define an enum that is equivalent to the follow‐
       ing C code:

	 typedef enum {
	       LAME_CLIENT_IS_CONNECTED,
	       LAME_CLIENT_NONE = 9,
	       LAME_CLIENT_LAST
	 } TestEnum;

C++ MODE
       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 gen‐
       erated 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++ com‐
       piler.

OVERRIDING THE GET_TYPE METHOD
       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.  So it is possible to override this function.
       To  do  so,  just  define  a new public method called get_type, with no
       arguments.  Example:

	 public GType
	 get_type (void)
	 {
	    /* code goes here */
	    return some_type;
	 }

INTERFACES
       Currently gob will only allow you to  implement	interfaces  (that  is,
       define  new  classes which implement an interface) and doesn´t yet have
       support for making new interfaces, but this  will  be  coming  at  some
       point in the future.

       To define a class that implements an interface add a class flag ´inter‐
       face´ with the type name of the interface  as  an  argument.   Then  to
       implement  a  specific  method  of  the	interface, just add ´interface
       <typename>´ before the method definition.  The method can, and probably
       should be, private.

       The  following  example	implements  a  new object, that implements the
       Gtk:Tree:Model interface and implements the get_flags  method  of  that
       interface.   Do	note that except for standard (GTK+ and glib) specific
       interfaces which seem to have a non-standard  name  for	the  interface
       structure,  the	structure should end with and Iface, if you are imple‐
       menting an interface.  That is for example for the Gtk:Tree:Model,  the
       structure  containing  the table of methods should be named GtkTreeMod‐
       elIface.
	 class Some:Object from G:Object
		 (interface Gtk:Tree:Model)
	 {
		 /* function implemented for the Gtk:Tree:Model interface */
		 interface Gtk:Tree:Model
		 private GtkTreeModelFlags
		 get_flags (Gtk:Tree:Model *self (check null type))
		 {
		      /* Here would be the implementation */
		      return (GtkTreeModelFlags)0;
		 }
	 }

       If you want to implement multiple interfaces just list more class  flag
       lines as follows:

	 class Some:Object from G:Object
		 (interface Gtk:Tree:Model)
		 (interface Gtk:Editable)
	 {
		 /* ... */
	 }

DIRECT BonoboObject SUPPORT
       If  you	want to build a BonoboObject class gob2 has direct support for
       these.  Just create a new object that derives from Bonobo:Object.  Then
       use a "BonoboObject" 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
       BonoboObject  keyword.	For  example  imagine  you  have  an interface
       GNOME/Foo/SomeInterface, with a	method	fooBar	that  takes  a	single
       string:

	 class Foo:Some:Interface from Bonobo:Object
	   (BonoboObject GNOME_Foo_SomeInterface) {

		 BonoboObject
		 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 */
	 }

       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  assign‐
       ment  warning.  You should check the header file generated by orbit-idl
       and see the epv structure for the correct prototypes if you can´t  fig‐
       ure 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.

DIRECT LIBGLADE SUPPORT
       Gob  can	 simplify  writing a libglade class.  Just create a new object
       that derives from a GtkContainer widget.	 Then use a  "GladeXML"	 class
       flag  with  the	glade  file  name, root widget and optional domain  as
       arguments between double quotes.	 For example:

       class My:Glade from Gtk:Window (GladeXML "gob-libglade.glade" "root")
       {
	 ....
       }

       Note however that then "gob-libglade.glade" would have  to  be  in  the
       current directory.  You could specify a path, but that may not work for
       all installations.  You can replace the glade filename with a token  to
       be used in the generated .c file and you can then have a macro with the
       filename, as follows:

       class My:Glade from Gtk:Window (GladeXML GLADE_FILE "root")
       {
	 ....
       }

       And somewhere in your header files you would have

       #define GLADE_FILE "/path/to/file.glade"

       You can declare widgets as data members by adding a 'GladeXML'  to  the
       definition.

       private Gtk:Button * button1 GladeXML;

       This will automatically set the "button1" from the GladeXML file.

       All  signals  created  with  glade  are	automatically connected if you
       defined those class methods in your  class.   For  example  suppose  in
       glade  that  we	set  the  "connect" signal on button1 to go to on_but‐
       ton1_clicked, then in our gob file we can just write:

       public void
       on_button1_clicked(self, GtkButton * button)
       {
       }

       See the examples directory for a full example.  Note that this  feature
       requires version at least 2.0.12.

IDENTIFIER CONFLICTS
       Gob  will need to define some local variables and functions in the gen‐
       erated 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	__par‐
       ent__ 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.

       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, SELF_TYPE,
       ARG, VAR, PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR
       and GOB_VERSION_PATCHLEVEL.

       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.

USING GTK-DOC STYLE INLINE DOCUMENTATION
       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 doc‐
       umentation comments in your %{ %} section which will then be put verba‐
       tim into the output source file.	 This is the way you  should  use  for
       functions you define outside of the class.

       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:

	 class Gtk:Button:Example from Gtk:Button {
		 /**
		  * new:
		  *
		  * Makes a new #GtkButtonExample widget
		  *
		  * Returns: a new widget
		  **/
		 public
		 GtkWidget *
		 new(void)
		 {
			 return (GtkWidget *)GET_NEW;
		 }
	 }

       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.

DEALING WITH CIRCULAR HEADERS
       Sometimes  you may need to use an object of type MyObjectA in the MyOb‐
       jectB 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  include  a
       protecting  define  before it declares the typedef.  This define is the
       __TYPEDEF_<upper case object name>__.  So  inside  my-object-a.h	 there
       will be this:

	 #ifndef __TYPEDEF_MY_OBJECT_A__
	 #define __TYPEDEF_MY_OBJECT_A__
	 typedef struct _MyObjectA MyObjectA;
	 #endif

       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.

       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	gener‐
       ated public header.

BUILDING WITH MAKE
       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 ´gob2´ is a tab, not spaces):

	 %.c %.h %-private.h: %.gob
		 gob2 $<

BUILDING WITH AUTOCONF and AUTOMAKE
       This is a little bit more involved.  Basically the first thing to do is
       to  check for GOB2 in your configure.in file.  You can use the supplied
       m4 macro which will also check  the  version  of	 gob.	Basically  you
       include this:

	 GOB2_CHECK([2.0.0])

       This  will replace @GOB2@ in your makefiles with the full path of gob2.
       Thus when adding the generic rule to your Makefile.am file,  it	should
       look like:

	 %.c %.h %-private.h: %.gob
		 @GOB2@ $<

       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	 vari‐
       able.  You have to include both the .gob and the .c and .h files in the
       SOURCES for your program.

PREVENTING SPURIOUS BUILDS
       When nothing has changed you might not really want  to  rebuild	every‐
       thing  and  gob	provides  options  --no-touch (since 2.0.13) and --no-
       touch-headers to avoid this.  When working with build systems  such  as
       automake	 you  have  to be more careful as just using those options can
       cause automake to get confused and you will need to use something  like
       the following:

	 foo_SOURCES = foo.gob foo.gob.stamp foo.c foo.h foo-private.h
	 BUILT_SOURCES = foo.gob.stamp
	 MAINTAINERCLEANFILES = foo.gob.stamp

	 %.gob.stamp: %.gob
		 @GOB2@ --no-touch $<
		 @touch $@

DEBUGGING
       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.

       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.

M4 SUPPORT
       It is possible to have your .gob file also preprocessed by m4.  This is
       useful if you have a lot of files and you´d  like  to  have  some  pre‐
       processor  put in some common features.	All you have to do is add --m4
       to the command line of gob2 and gob2 will first run your	 file  through
       m4.   You can print the directory that is searched for m4 files by run‐
       ning "gob2 --m4-dir"

       All the arguments after --m4 will be passed to m4 itself, so it has  to
       be  the last gob2 argument on the command line.	This way you can spec‐
       ify arbitrary options to pass to m4.

BUGS
       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.

       Another thing is that  gob  ignores  preprocessor  macros.   Since  gob
       counts braces, the following code won´t work:

	 #ifdef SOME_DEFINE
	 if(foo) {
	 #else
	 if(bar) {
	 #endif
		 blah();
	 }

       To make this work, you´d have to do this:

	 #ifdef SOME_DEFINE
	 if(foo)
	 #else
	 if(bar)
	 #endif
	 {
		 blah();
	 }

       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 prob‐
       lematic.	 Basically, if you use gob, just don´t use the C  preprocessor
       too extensively.	 And if you use it make sure that you do not cross the
       boundaries of the C code segments.

       Comments will not get through to the generated files  unless  inside  C
       code.   This  is not the case for gtk-doc style comments which are sup‐
       ported.

       The short name aliases are actually implemented as  pointers  to	 func‐
       tions.	Thus  if  you  want to get the pointer of a function using the
       short name alias you can´t use the ´&´.	Thus:

	 void (*foo)(Self *);

	 /* this will NOT work */
	 foo = &self_short_name;

	 /* this will work */
	 foo = self_short_name;

	 /* Both of these will work */
	 foo = &my_class_long_name;
	 foo = my_class_long_name;

AUTHOR
       George Lebl <jirka@5z.com>

       GOB2 Homepage: http://www.jirka.org/gob.html

				  GOB2 2.0.17			       GOB2(1)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net