GNU Info
(gtk.info)Basics
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 Note: 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 Note: 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 Note: 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;
automatically generated by info2www version 1.2.2.9