3.2 Basic Concepts

The basis for the type system are the fundamental types. At run-time, they are represented by members of the GtkFundamentalType enumeration. For the static declarations, they are identified with a unique name.

Enumeration: GtkFundamentalType

This enumeration contains a member for each defined fundamental type. Most members are listed along with the description of their semantics, but one is listed here:

GTK_TYPE_INVALID

No valid type is derived from this. Use GTK_TYPE_INVALID to express exceptional situations. This member does not really correspond to a fundamental type and thus there is no name for it.

Data type: GtkType

The type GtkType holds the run-time representation of a type. It is an integer of a certain size. The follwing macros are defined to access the basic properties of a GtkType:

Macro: unsigned int GTK_TYPE_SEQNO (GtkType type)

Returns the sequence number of type. The sequence numbers are guaranteed to be dense, i.e., you can use them to index a table and the table need not be much larger than the number of different GtkTypes that you might encounter.

Macro: GtkFundamentalType GTK_FUNDAMENTAL_TYPE (GtkType type)

Returns the fundamental type of type.

Both macros simply access different bit-fields of a GtkType, so they are very efficient.

New types are registered with the gtk_type_unique function. Any kind oftype can be registered with gtk_type_unique but there are convenience functions for most fundamental types. Each fundamental type has its own interpretation of the rules below and these convenience functions should be used to automatically get the type registration right. So, don't be put off by the apparent complexity of the interface to gtk_type_unique. You will be using it only for new widgets, and there the rules are simple.

The GtkTypeInfo structure is used to communicate information to gtk_type_unique as opposed to passing in large numbers of parameters.

typedef struct _GtkTypeInfo GtkTypeInfo;

struct _GtkTypeInfo
{
  gchar *type_name;
  guint object_size;
  guint class_size;
  GtkClassInitFunc class_init_func;
  GtkObjectInitFunc object_init_func;
  gpointer reserved_1;
  gpointer reserved_2;
  GtkClassInitFunc base_class_init_func;
}

• The type_name field refers to the name of the type. This is the same name that is used in the static definitions. It is convention for the type name to be closely related to the name of the underlying C type. For example, the type name of the GtkObject structure is "GtkObject", and the name of the GtkWindowType enumeration is "GtkWindowType". Note that the C type corresponding to "GtkObject" is really a pointer to a GtkObject struct, but the name has no "*" in it.
• The object_size field refers to the size in bytes of the C structure for types that have such a structure. The easiest (and portable) means of computing this size is by using the C sizeof operator. For instance, the sizeof of the GtkObject structure is computed by doing sizeof (GtkObject). When the type has no associated structure or when you do not want to support the gtk_type_new function for the new type, set object_size to 0. Only types derived from GTK_TYPE_OBJECT can be handled by gtk_type_new, anyway.
• The class_size field refers to the size in bytes of the C structure for the class. Again, the sizeof operator should be used to compute this value. If you don't want to have a class structure for this type, set the field to 0. gtk_type_class will then always return NULL.
• The class_init_func and base_class_init_func fields are callbacks which are used by the type mechanism to initialize class specific fields. The single argument these functions take is a pointer to a class structure. When you do not need one or both of them, set the corresponding field to NULL. The class_init_func will be called at most once, right after the class structure of size class_size has been allocated. The interaction between class_init_func and base_class_init_func is only really useful for the full-fledged object system. It is described there see section 4. Objects.
• The object_init_func field is a callback which is used by the type mechanism to initialize object specific fields for structures that have been allocated via gtk_type_new. The single argument this functions takes is a pointer to an object structure. If you do not want any special object initialization to take place, set this to NULL. All object initialization functions for all types that are part of the inheritance chain are called, starting with the most basic type.

Function: guint gtk_type_unique (GtkType parent_type, GtkTypeInfo *type_info)

The parent_type is simply the new types parent type. If parent_type is GTK_TYPE_INVALID, then the new type is a new fundamental type. You should never register new fundamental types. type_info is a pointer to a structure which contains necessary information for construction of the new type.

You can only register a specific name once.

Function: gchar* gtk_type_name (GtkType type)

The returned string is the name of type as specified to gtk_type_unique.

Function: GtkType gtk_type_from_name (guchar *name)

Return the type associated with name. If there is no type associated with name, then GTK_TYPE_INVALID will be returned.

Function: GtkType gtk_type_parent (GtkType type)

Returns the parent type of type or GTK_TYPE_INVALID if type is a fundamental type.

Function: gpointer gtk_type_class (GtkType type)

Returns the initialized class structure for type. The class structure is actually created and initialized the first time it is needed. Refer to see section 4. Objects for details on how this initialization works for GTK_TYPE_OBJECT derived types.

The returned structure is shared by all objects of type and, as such, should not be modified.

Function: gpointer gtk_type_new (GtkType type)

Returns a new instance of an type object. This works only for GTK_TYPE_OBJECT derived types. Please see see section 4. Objects.

Function: void gtk_type_describe_heritage (GtkType type)

Prints the type heritage for type. The heritage for a type includes the type and all its parent types up the type tree.

Function: void gtk_type_describe_tree (GtkType type, gboolean show_size)

Prints the type tree which starts at type. show_size is a boolean which determines whether type sizes are printed.

Function: gboolean gtk_type_is_a (GtkType type, GtkType is_a_type)

A predicate function which determines whether the relation type is_a is_a_type is true.

Values of all types can be handled uniformly by storing them into a GtkArg structure. The GtkArg has the following fields:

gchar *name

This can be used to give the value represented by this GtkArg structure a name. It is not used much.

GtkType type

The type of this value.

union d

A big union that has (at least conceptually) one member for each fundamental type. You should not access these members directly. Rather, use the GTK_VALUE_* macros. There is one macro for each fundamental type, and its name is derived from the name of the GtkFundamentalType enumeration members simply by replacing "Gtk_TYPE" with "GTK_VALUE". All GTK_VALUE_* macros take a GtkArg structure as their only parameter (not a pointer) and evaluate to a lvalue.

For example, the accessor for the fundamental type GTK_TYPE_INT is called GTK_VALUE_INT and you could use it like this:

GtkArg value;

value.name = NULL;
value.type = GTK_TYPE_INT;
GTK_VALUE_INT(value) = 7;

Go to the first, previous, next, last section, table of contents.