diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml index 8d78dc94a..95ce1b525 100644 --- a/docs/reference/gobject/tut_gobject.xml +++ b/docs/reference/gobject/tut_gobject.xml @@ -126,8 +126,8 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); Finally, at one point or another, g_object_constructor is invoked by the last constructor in the chain. This function allocates the object's instance' buffer through g_type_create_instance - which means that the instance_init function is invoked at this point if one - was registered. After instance_init returns, the object is fully initialized and should be + which means that the instance_init function is invoked at this point if one + was registered. After instance_init returns, the object is fully initialized and should be ready to answer any user-request. When g_type_create_instance returns, g_object_constructor sets the construction properties (i.e. the properties which were given to g_object_new) and returns @@ -152,7 +152,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); Invocation time - Function Invoked + Function invoked Function's parameters Remark @@ -160,17 +160,17 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); First call to g_object_new for target type - target type's base_init function + target type's base_init function On the inheritance tree of classes from fundamental type to target type. - base_init is invoked once for each class structure. + base_init is invoked once for each class structure. I have no real idea on how this can be used. If you have a good real-life - example of how a class' base_init can be used, please, let me know. + example of how a class' base_init can be used, please, let me know. - target type's class_init function + target type's class_init function On target type's class structure Here, you should make sure to initialize or override class methods (that is, @@ -180,14 +180,14 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - interface' base_init function - On interface' vtable + interface's base_init function + On interface's vtable - interface' interface_init function - On interface' vtable + interface's interface_init function + On interface's vtable @@ -203,12 +203,12 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - type's instance_init function + type's instance_init function On the inheritance tree of classes from fundamental type to target type. - the instance_init provided for each type is invoked once for each instance + the instance_init provided for each type is invoked once for each instance structure. - Provide an instance_init function to initialize your object before its construction + Provide an instance_init function to initialize your object before its construction properties are set. This is the preferred way to initialize a GObject instance. This function is equivalent to C++ constructors. @@ -221,12 +221,12 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); Readers should feel concerned about one little twist in the order in which functions are invoked: while, technically, the class' constructor - method is called before the GType's instance_init - function (since g_type_create_instance which calls instance_init is called by + method is called before the GType's instance_init + function (since g_type_create_instance which calls instance_init is called by g_object_constructor which is the top-level class constructor method and to which users are expected to chain to), the user's code which runs in a user-provided constructor will always - run after GType's instance_init function since the + run after GType's instance_init function since the user-provided constructor must (you've been warned) chain up before doing anything useful. @@ -308,7 +308,7 @@ void g_object_run_dispose (GObject *object); Invocation time - Function Invoked + Function invoked Function's parameters Remark @@ -349,16 +349,16 @@ void g_object_run_dispose (GObject *object); Last call to g_object_unref for the last instance of target type - interface' interface_finalize function - On interface' vtable + interface's interface_finalize function + On interface's vtable Never used in practice. Unlikely you will need it. - interface' base_finalize function - On interface' vtable + interface's base_finalize function + On interface's vtable Never used in practice. Unlikely you will need it. @@ -375,7 +375,7 @@ void g_object_run_dispose (GObject *object); type's base_finalize function On the inheritance tree of classes from fundamental type to target type. - base_init is invoked once for each class structure. + base_init is invoked once for each class structure. Never used in practice. Unlikely you will need it. @@ -413,12 +413,7 @@ void g_object_run_dispose (GObject *object); Reference counts and cycles - - - Note: the following section was inspired by James Henstridge. I guess this means that - all praise and all curses will be directly forwarded to him. - - + GObject's memory management model was designed to be easily integrated in existing code using garbage collection. This is why the destruction process is split in two phases: @@ -455,10 +450,9 @@ void g_object_run_dispose (GObject *object); - The above example, which might seem a bit contrived can really happen if your - GObject's are being handled by language bindings. I would thus suggest the rules stated above - for object destruction are closely followed. Otherwise, Bad Bad Things - will happen. + The above example, which might seem a bit contrived, can really happen if + GObjects are being handled by language bindings — hence the rules for + object destruction should be closely followed. @@ -469,7 +463,7 @@ void g_object_run_dispose (GObject *object); One of GObject's nice features is its generic get/set mechanism for object properties. When an object - is instantiated, the object's class_init handler should be used to register + is instantiated, the object's class_init handler should be used to register the object's properties with g_object_class_install_properties (implemented in gobject.c). @@ -589,12 +583,12 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); g_value_unset (&val); - The client code just above looks simple but a lot of things happen under the hood: + The client code above looks simple but a lot of things happen under the hood: g_object_set_property first ensures a property - with this name was registered in bar's class_init handler. If so it walks the class hierarchy, + with this name was registered in bar's class_init handler. If so it walks the class hierarchy, from bottom, most derived type, to top, fundamental type to find the class which registered that property. It then tries to convert the user-provided GValue into a GValue whose type is that of the associated property. @@ -620,7 +614,7 @@ g_value_unset (&val); data stored in the GValue matches the characteristics specified by the property's GParamSpec. Here, the GParamSpec we - provided in class_init has a validation function which makes sure that the GValue + provided in class_init has a validation function which makes sure that the GValue contains a value which respects the minimum and maximum bounds of the GParamSpec. In the example above, the client's GValue does not respect these constraints (it is set to 11, while the maximum is 10). As such, the @@ -675,7 +669,7 @@ g_value_unset (&val); It is interesting to note that the g_object_set and - g_object_set_valist (vararg version) functions can be used to set + g_object_set_valist (variadic version) functions can be used to set multiple properties at once. The client code shown above can then be re-written as: MamanBar *foo; @@ -692,7 +686,7 @@ g_object_set (G_OBJECT (foo), Of course, the _get versions are also available: g_object_get - and g_object_get_valist (vararg version) can be used to get numerous + and g_object_get_valist (variadic version) can be used to get numerous properties at once.