How To define and implement a new GObject?

Clearly, this is one of the most common question people ask: they just want to crank code and implement a subclass of a GObject. Sometimes because they want to create their own class hierarchy, sometimes because they want to subclass one of GTK+'s widget. This chapter will focus on the implementation of a subtype of GObject. The sample source code associated to this section can be found in the documentation's source tarball, in the sample/gobject directory:

maman-bar.{h|c}: this is the source for a object which derives from GObject and which shows how to declare different types of methods on the object.
maman-subbar.{h|c}: this is the source for a object which derives from MamanBar and which shows how to override some of its parent's methods.
maman-foo.{h|c}: this is the source for an object which derives from GObject and which declares a signal.
test.c: this is the main source which instantiates an instance of type and exercises their API.

Boilerplate header code

The first step before writing the code for your GObject is to write the type's header which contains the needed type, function and macro definitions. Each of these elements is nothing but a convention which is followed not only by GTK+'s code but also by most users of GObject. If you feel the need not to obey the rules stated below, think about it twice:

If your users are a bit accustomed to GTK+ code or any Glib code, they will be a bit surprised and getting used to the conventions you decided upon will take time (money) and will make them grumpy (not a good thing)
You must assess the fact that these conventions might have been designed by both smart and experienced people: maybe they were at least partly right. Try to put your ego aside.

Pick a name convention for your headers and source code and stick to it:

use a dash to separate the prefix from the typename: maman-bar.h and maman-bar.c (this is the convention used by Nautilus and most GNOME libraries).
use an underscore to separate the prefix from the typename: maman_bar.h and maman_bar.c.
Do not separate the prefix from the typename: mamanbar.h and mamanbar.c. (this is the convention used by GTK+)

I personally like the first solution better: it makes reading file names easier for those with poor eyesight like me.

When you need some private (internal) declarations in several (sub)classes, you can define them in a private header file which is often named by appending the private keyword to the public header name. For example, one could use maman-bar-private.h, maman_bar_private.h or mamanbarprivate.h. Typically, such private header files are not installed.

The basic conventions for any header which exposes a GType are described in the section called “Conventions”. Most GObject-based code also obeys onf of the following conventions: pick one and stick to it.

If you want to declare a type named bar with prefix maman, name the type instance MamanBar and its class MamanBarClass (name is case-sensitive). It is customary to declare them with code similar to the following:

/*
 * Copyright/Licensing information.
 */

#ifndef MAMAN_BAR_H
#define MAMAN_BAR_H

/*
 * Potentially, include other headers on which this header depends.
 */

/*
 * Type macros.
 */

typedef struct _MamanBar MamanBar;
typedef struct _MamanBarClass MamanBarClass;

struct _MamanBar {
  GObject parent;
  /* instance members */
};

struct _MamanBarClass {
  GObjectClass parent;
  /* class members */
};

/* used by MAMAN_BAR_TYPE */
GType maman_bar_get_type (void);

/*
 * Method definitions.
 */

#endif

Most GTK+ types declare their private fields in the public header with a /* private */ comment, relying on their user's intelligence not to try to play with these fields. Fields not marked private are considered public by default. The /* protected */ comment (same semantics as those of C++) is also used, mainly in the GType library, in code written by Tim Janik.
```
struct _MamanBar {
  GObject parent;

  /*< private >*/
  int hsize;
};
```
All of Nautilus code and a lot of GNOME libraries use private indirection members, as described by Herb Sutter in his Pimpl articles (see Compilation Firewalls and The Fast Pimpl Idiom : he summarizes the different issues better than I will).
```
typedef struct _MamanBarPrivate MamanBarPrivate;
struct _MamanBar {
  GObject parent;
    
  /*< private >*/
  MamanBarPrivate *priv;
};
```
Note

Do not call this private, as that is a registered c++ keyword.

The private structure is then defined in the .c file, instantiated in the object's init function and destroyed in the object's finalize function.
```
static void
maman_bar_finalize (GObject *object) {
  MamanBar *self = MAMAN_BAR (object);
  /* do stuff */
  g_free (self->priv);
}

static void
maman_bar_init (GTypeInstance *instance, gpointer g_class) {
  MamanBar *self = MAMAN_BAR (instance);
  self->priv = g_new0 (MamanBarPrivate,1);
  /* do stuff */
}
```
A similar alternative, available since Glib version 2.4, is to define a private structure in the .c file, declare it as a private structure in maman_bar_class_init using g_type_class_add_private. Instead of allocating memory in maman_bar_init a pointer to the private memory area is stored in the instance to allow convenient access to this structure. A private structure will then be attached to each newly created object by the GObject system. You dont need to free or allocate the private structure, only the objects or pointers that it may contain. Another advantage of this to the previous version is that is lessens memory fragmentation, as the public and private parts of the instance memory are allocated at once.
```
typedef struct _MamanBarPrivate MamanBarPrivate;

struct _MamanBarPrivate {
  int private_field;
};

static void
maman_bar_class_init (MamanBarClass *klass)
{
  ...
  g_type_class_add_private (klass, sizeof (MamanBarPrivate));
  ...
}

static void
maman_bar_init (GTypeInstance *instance, gpointer g_class) {
  MamanBar *self = MAMAN_BAR (instance);
  self->priv = G_TYPE_INSTANCE_GET_PRIVATE (self, MAMAN_BAR_TYPE, MamanBarPrivate);
  /* do stuff */
}
```

Finally, there are different header include conventions. Again, pick one and stick to it. I personally use indifferently any of the two, depending on the codebase I work on: the rule is consistency.

Some people add at the top of their headers a number of #include directives to pull in all the headers needed to compile client code. This allows client code to simply #include "maman-bar.h".
Other do not #include anything and expect the client to #include themselves the headers they need before including your header. This speeds up compilation because it minimizes the amount of pre-processor work. This can be used in conjunction with the re-declaration of certain unused types in the client code to minimize compile-time dependencies and thus speed up compilation.

How To define and implement a new GObject?

Boilerplate header code

Note