GObject Reference Manual: Conventions

## Conventions

There are a number of conventions users are expected to follow when creating new types which are to be exported in a header file:

- Use the `object_method` pattern for function names: to invoke the method named foo on an instance of object type bar, call `bar_foo`.

- Use prefixing to avoid namespace conflicts with other projects. If your library (or application) is named Maman, [3] prefix all your function names with maman_. For example: `maman_object_method`.

- Create a macro named `PREFIX_TYPE_OBJECT` which always returns the GType for the associated object type. For an object of type Bar in a library prefixed by maman, use: `MAMAN_TYPE_BAR`. It is common although not a convention to implement this macro using either a global static variable or a function named `prefix_object_get_type`. We will follow the function pattern wherever possible in this document.

- Create a macro named `PREFIX_OBJECT (obj)` which returns a pointer of type PrefixObject. This macro is used to enforce static type safety by doing explicit casts wherever needed. It also enforces dynamic type safety by doing runtime checks. It is possible to disable the dynamic type checks in production builds (see building glib). For example, we would create `MAMAN_BAR (obj)` to keep the previous example.

- If the type is classed, create a macro named `PREFIX_OBJECT_CLASS (klass)`. This macro is strictly equivalent to the previous casting macro: it does static casting with dynamic type checking of class structures. It is expected to return a pointer to a class structure of type PrefixObjectClass. Again, an example is: `MAMAN_BAR_CLASS`.

- Create a macro named `PREFIX_IS_BAR (obj)`: this macro is expected to return a gboolean which indicates whether or not the input object instance pointer of type BAR.

- If the type is classed, create a macro named `PREFIX_IS_OBJECT_CLASS (klass)` which, as above, returns a boolean if the input class pointer is a pointer to a class of type OBJECT.

- If the type is classed, create a macro named `PREFIX_OBJECT_GET_CLASS (obj)` which returns the class pointer associated to an instance of a given type. This macro is used for static and dynamic type safety purposes (just like the previous casting macros).

The implementation of these macros is pretty straightforward: a number of simple-to-use macros are provided in `gtype.h`. For the example we used above, we would write the following trivial code to declare the macros:

    1
    2
    3
    4
    5
    6
    #define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
    #define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
    #define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
    #define MAMAN_IS_BAR(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
    #define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
    #define MAMAN_BAR_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))

Stick to the naming `klass` as `class` is a registered c++ keyword.

The following code shows how to implement the `maman_bar_get_type` function:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    GType maman_bar_get_type (void)
    {
      static GType type = 0;
      if (type == 0) {
        const GTypeInfo info = {
          /* You fill this structure. */
        };
        type = g_type_register_static (G_TYPE_OBJECT,
                                       "MamanBarType",
                                       &info, 0);
      }
      return type;
    }

If you have no special requirements you can use the `G_DEFINE_TYPE` macro to define a class:

    1
    G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)

[3] Maman is the French word for mum or mother - nothing more and nothing less.