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

- Type names (including object names) must be at least three characters long and start with ‘a–z’, ‘A–Z’ or ‘_’.

- Use the `object_method` pattern for function names: to invoke the method named `save` on an instance of object type file, call `file_save`.

- Use prefixing to avoid namespace conflicts with other projects. If your library (or application) is named Viewer, prefix all your function names with viewer_. For example: `viewer_object_method`.

- Create a macro named `PREFIX_TYPE_OBJECT` which always returns the GType for the associated object type. For an object of type File in the Viewer namespace, use: `VIEWER_TYPE_FILE`. This macro is implemented using a function named `prefix_object_get_type`; for example, `viewer_file_get_type`.

- Use `G_DECLARE_FINAL_TYPE` or `G_DECLARE_DERIVABLE_TYPE` to define various other conventional macros for your object:

  - `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 `VIEWER_FILE (obj)` to keep the previous example.

  - `PREFIX_OBJECT_CLASS (klass)`, which 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. An example is: `VIEWER_FILE_CLASS`.

  - `PREFIX_IS_OBJECT (obj)`, which returns a gboolean which indicates whether the input object instance pointer is non-NULL and of type OBJECT. For example, `VIEWER_IS_FILE`.

  - `PREFIX_IS_OBJECT_CLASS (klass)`, which returns a boolean if the input class pointer is a pointer to a class of type OBJECT. For example, `VIEWER_IS_FILE_CLASS`.

  - `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). For example, `VIEWER_FILE_GET_CLASS`.

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
    #define VIEWER_TYPE_FILE viewer_file_get_type ()
    G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)

Unless your code has special requirements, you can use the `G_DEFINE_TYPE` macro to define a class:

    1
    G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)

Otherwise, the `viewer_file_get_type` function must be implemented manually:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    GType viewer_file_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,
                                       "ViewerFile",
                                       &info, 0);
      }
      return type;
    }