|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>The GObject base class: GObject Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GObject Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="pt01.html" title="Part I. Concepts">
|
|
Packit |
ae235b |
<link rel="prev" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
|
|
Packit |
ae235b |
<link rel="next" href="gobject-memory.html" title="Object memory management">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The GObject base class
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Object instantiation
|
|
Packit |
ae235b |
Object memory management
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Reference count
|
|
Packit |
ae235b |
Weak References
|
|
Packit |
ae235b |
Reference counts and cycles
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Object properties
|
|
Packit |
ae235b |
- Accessing multiple properties at once
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The previous chapter discussed the details of GLib's Dynamic Type System.
|
|
Packit |
ae235b |
The GObject library also contains an implementation for a base fundamental
|
|
Packit |
ae235b |
type named GObject.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GObject is a fundamental classed instantiable type. It implements:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Memory management with reference counting
|
|
Packit |
ae235b |
Construction/Destruction of instances
|
|
Packit |
ae235b |
Generic per-object properties with set/get function pairs
|
|
Packit |
ae235b |
Easy use of signals
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer)
|
|
Packit |
ae235b |
inherit from GObject which is why it is important to understand
|
|
Packit |
ae235b |
the details of how it works.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Object instantiation
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The g_object_new
|
|
Packit |
ae235b |
family of functions can be used to instantiate any GType which inherits
|
|
Packit |
ae235b |
from the GObject base type. All these functions make sure the class and
|
|
Packit |
ae235b |
instance structures have been correctly initialized by GLib's type system
|
|
Packit |
ae235b |
and then invoke at one point or another the constructor class method
|
|
Packit |
ae235b |
which is used to:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Allocate and clear memory through g_type_create_instance,
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Initialize the object's instance with the construction properties.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Although one can expect all class and instance members (except the fields
|
|
Packit |
ae235b |
pointing to the parents) to be set to zero, some consider it good practice
|
|
Packit |
ae235b |
to explicitly set them.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Once all construction operations have been completed and constructor
|
|
Packit |
ae235b |
properties set, the constructed class method is called.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Objects which inherit from GObject are allowed to override this
|
|
Packit |
ae235b |
constructed class method.
|
|
Packit |
ae235b |
The example below shows how ViewerFile overrides the parent's construction process:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
2
|
|
Packit |
ae235b |
3
|
|
Packit |
ae235b |
4
|
|
Packit |
ae235b |
5
|
|
Packit |
ae235b |
6
|
|
Packit |
ae235b |
7
|
|
Packit |
ae235b |
8
|
|
Packit |
ae235b |
9
|
|
Packit |
ae235b |
10
|
|
Packit |
ae235b |
11
|
|
Packit |
ae235b |
12
|
|
Packit |
ae235b |
13
|
|
Packit |
ae235b |
14
|
|
Packit |
ae235b |
15
|
|
Packit |
ae235b |
16
|
|
Packit |
ae235b |
17
|
|
Packit |
ae235b |
18
|
|
Packit |
ae235b |
19
|
|
Packit |
ae235b |
20
|
|
Packit |
ae235b |
21
|
|
Packit |
ae235b |
22
|
|
Packit |
ae235b |
23
|
|
Packit |
ae235b |
24
|
|
Packit |
ae235b |
25
|
|
Packit |
ae235b |
26
|
|
Packit |
ae235b |
27
|
|
Packit |
ae235b |
28
|
|
Packit |
ae235b |
29
|
|
Packit |
ae235b |
30
|
|
Packit |
ae235b |
31
|
|
Packit |
ae235b |
32
|
|
Packit |
ae235b |
33
|
|
Packit |
ae235b |
34
|
|
Packit |
ae235b |
35
|
|
Packit |
ae235b |
36
|
|
Packit |
ae235b |
#define VIEWER_TYPE_FILE viewer_file_get_type ()
|
|
Packit |
ae235b |
G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct _ViewerFile
|
|
Packit |
ae235b |
{
|
|
Packit |
ae235b |
GObject parent_instance;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
};
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
static void
|
|
Packit |
ae235b |
viewer_file_constructed (GObject *obj)
|
|
Packit |
ae235b |
{
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_OBJECT_CLASS (viewer_file_parent_class)->constructed (obj);
|
|
Packit |
ae235b |
}
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
static void
|
|
Packit |
ae235b |
viewer_file_class_init (ViewerFileClass *klass)
|
|
Packit |
ae235b |
{
|
|
Packit |
ae235b |
GObjectClass *object_class = G_OBJECT_CLASS (klass);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
object_class->constructed = viewer_file_constructed;
|
|
Packit |
ae235b |
}
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
static void
|
|
Packit |
ae235b |
viewer_file_init (ViewerFile *self)
|
|
Packit |
ae235b |
{
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
}
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If the user instantiates an object ViewerFile with:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
ViewerFile *file = g_object_new (VIEWER_TYPE_FILE, NULL);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If this is the first instantiation of such an object, the
|
|
Packit |
ae235b |
viewer_file_class_init function will be invoked
|
|
Packit |
ae235b |
after any viewer_file_base_class_init function.
|
|
Packit |
ae235b |
This will make sure the class structure of this new object is
|
|
Packit |
ae235b |
correctly initialized. Here, viewer_file_class_init
|
|
Packit |
ae235b |
is expected to override the object's class methods and setup the
|
|
Packit |
ae235b |
class' own methods. In the example above, the constructed
|
|
Packit |
ae235b |
method is the only overridden method: it is set to
|
|
Packit |
ae235b |
viewer_file_constructed.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Once g_object_new has obtained a reference to an initialized
|
|
Packit |
ae235b |
class structure, it invokes its constructor method to create an instance of the new
|
|
Packit |
ae235b |
object, if the constructor has been overridden in viewer_file_class_init.
|
|
Packit |
ae235b |
Overridden constructors must chain up to their parent’s constructor. In
|
|
Packit |
ae235b |
order to find the parent class and chain up to the parent class
|
|
Packit |
ae235b |
constructor, we can use the viewer_file_parent_class
|
|
Packit |
ae235b |
pointer that has been set up for us by the
|
|
Packit |
ae235b |
G_DEFINE_TYPE
|
|
Packit |
ae235b |
macro.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Finally, at one point or another, g_object_constructor is invoked
|
|
Packit |
ae235b |
by the last constructor in the chain. This function allocates the object's instance buffer
|
|
Packit |
ae235b |
through g_type_create_instance
|
|
Packit |
ae235b |
which means that the instance_init function is invoked at this point if one
|
|
Packit |
ae235b |
was registered. After instance_init returns, the object is fully initialized and should be
|
|
Packit |
ae235b |
ready to have its methods called by the user. When
|
|
Packit |
ae235b |
g_type_create_instance
|
|
Packit |
ae235b |
returns, g_object_constructor sets the construction properties
|
|
Packit |
ae235b |
(i.e. the properties which were given to g_object_new) and returns
|
|
Packit |
ae235b |
to the user's constructor.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The process described above might seem a bit complicated, but it can be
|
|
Packit |
ae235b |
summarized easily by the table below which lists the functions invoked
|
|
Packit |
ae235b |
by g_object_new
|
|
Packit |
ae235b |
and their order of invocation:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Table 4. g_object_new
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Invocation time
|
|
Packit |
ae235b |
Function invoked
|
|
Packit |
ae235b |
Function's parameters
|
|
Packit |
ae235b |
Remark
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
First call to g_object_new for target type
|
|
Packit |
ae235b |
target type's base_init function
|
|
Packit |
ae235b |
On the inheritance tree of classes from fundamental type to target type.
|
|
Packit |
ae235b |
base_init is invoked once for each class structure.
|
|
Packit |
ae235b |
Never used in practice. Unlikely you will need it.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
target type's class_init function
|
|
Packit |
ae235b |
On target type's class structure
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Here, you should make sure to initialize or override class methods (that is,
|
|
Packit |
ae235b |
assign to each class' method its function pointer) and create the signals and
|
|
Packit |
ae235b |
the properties associated to your object.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
interface's base_init function
|
|
Packit |
ae235b |
On interface's vtable
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
interface's interface_init function
|
|
Packit |
ae235b |
On interface's vtable
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Each call to g_object_new for target type
|
|
Packit |
ae235b |
target type's class constructor method: GObjectClass->constructor
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
On object's instance
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If you need to handle construct properties in a custom way, or implement a singleton class, override the constructor
|
|
Packit |
ae235b |
method and make sure to chain up to the object's
|
|
Packit |
ae235b |
parent class before doing your own initialization.
|
|
Packit |
ae235b |
In doubt, do not override the constructor method.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
type's instance_init function
|
|
Packit |
ae235b |
On the inheritance tree of classes from fundamental type to target type.
|
|
Packit |
ae235b |
the instance_init provided for each type is invoked once for each instance
|
|
Packit |
ae235b |
structure.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Provide an instance_init function to initialize your object before its construction
|
|
Packit |
ae235b |
properties are set. This is the preferred way to initialize a GObject instance.
|
|
Packit |
ae235b |
This function is equivalent to C++ constructors.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
target type's class constructed method: GObjectClass->constructed
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
On object's instance
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If you need to perform object initialization steps after all construct properties have been set.
|
|
Packit |
ae235b |
This is the final step in the object initialization process, and is only called if the constructor
|
|
Packit |
ae235b |
method returned a new object instance (rather than, for example, an existing singleton).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Readers should feel concerned about one little twist in the order in
|
|
Packit |
ae235b |
which functions are invoked: while, technically, the class' constructor
|
|
Packit |
ae235b |
method is called before the GType's instance_init
|
|
Packit |
ae235b |
function (since g_type_create_instance which calls instance_init is called by
|
|
Packit |
ae235b |
g_object_constructor which is the top-level class
|
|
Packit |
ae235b |
constructor method and to which users are expected to chain to), the
|
|
Packit |
ae235b |
user's code which runs in a user-provided constructor will always
|
|
Packit |
ae235b |
run after GType's instance_init function since the
|
|
Packit |
ae235b |
user-provided constructor must (you've been warned)
|
|
Packit |
ae235b |
chain up before doing anything useful.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|