Function Macro

GObjectDECLARE_DERIVABLE_TYPE

Declaration [src]

#define G_DECLARE_DERIVABLE_TYPE (
  ModuleObjName,
  module_obj_name,
  MODULE,
  OBJ_NAME,
  ParentName
)

Description [src]

A convenience macro for emitting the usual declarations in the header file for a type which is intended to be subclassed.

You might use it in a header as follows:

#ifndef _gtk_frobber_h_
#define _gtk_frobber_h_

#define GTK_TYPE_FROBBER gtk_frobber_get_type ()
GDK_AVAILABLE_IN_3_12
G_DECLARE_DERIVABLE_TYPE (GtkFrobber, gtk_frobber, GTK, FROBBER, GtkWidget)

struct _GtkFrobberClass
{
  GtkWidgetClass parent_class;

  void (* handle_frob)  (GtkFrobber *frobber,
                         guint       n_frobs);

  gpointer padding[12];
};

GtkWidget *    gtk_frobber_new   (void);

...

#endif

This results in the following things happening:

  • the usual gtk_frobber_get_type() function is declared with a return type of GType

  • the GtkFrobber struct is created with GtkWidget as the first and only item. You are expected to use a private structure from your .c file to store your instance variables.

  • the GtkFrobberClass type is defined as a typedef to struct _GtkFrobberClass, which is left undefined. You should do this from the header file directly after you use the macro.

  • the GTK_FROBBER() and GTK_FROBBER_CLASS() casts are emitted as static inline functions along with the GTK_IS_FROBBER() and GTK_IS_FROBBER_CLASS() type checking functions and GTK_FROBBER_GET_CLASS() function.

  • g_autoptr() support being added for your type, based on the type of your parent class

You can only use this function if your parent type also supports g_autoptr().

Because the type macro (GTK_TYPE_FROBBER in the above example) is not a callable, you must continue to manually define this as a macro for yourself.

The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros.

If you are writing a library, it is important to note that it is possible to convert a type from using G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be subclassed. Once a class structure has been exposed it is not possible to change its size or remove or reorder items without breaking the API and/or ABI. If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). If you want to declare a class without exposing the class or instance structures, use G_DECLARE_FINAL_TYPE().

If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your class structure to leave space for the addition of future virtual functions.

Available since:2.44

Parameters

ModuleObjName -
 

The name of the new type, in camel case (like GtkWidget)

module_obj_name -
 

The name of the new type in lowercase, with words separated by _ (like gtk_widget)

MODULE -
 

The name of the module, in all caps (like GTK)

OBJ_NAME -
 

The bare name of the type, in all caps (like WIDGET)

ParentName -
 

The name of the parent type, in camel case (like GtkWidget)