From 0344e6cb83b338c8ba23d9ea8aa7a9fffa8d146e Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 20 Feb 2015 12:51:18 +0000 Subject: [PATCH] docs: Add missing elements to GObject how-to Break the text up a little with some formatting. https://bugzilla.gnome.org/show_bug.cgi?id=744060 --- docs/reference/gobject/tut_howto.xml | 57 ++++++++++++++++------------ 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml index 42edfa645..149f97942 100644 --- a/docs/reference/gobject/tut_howto.xml +++ b/docs/reference/gobject/tut_howto.xml @@ -273,14 +273,16 @@ G_DEFINE_TYPE_WITH_PRIVATE (MamanBar, maman_bar, G_TYPE_OBJECT) shows what user-provided functions are invoked during object instantiation and in which order they are invoked. A user looking for the equivalent of the simple C++ constructor function should use - the instance_init method. It will be invoked after all the parent's instance_init + the instance_init method. It will be invoked after + all the parents’ instance_init functions have been invoked. It cannot take arbitrary construction parameters (as in C++) but if your object needs arbitrary parameters to complete initialization, you can use construction properties. - Construction properties will be set only after all instance_init functions have run. + Construction properties will be set only after all + instance_init functions have run. No object reference will be returned to the client of g_object_new until all the construction properties have been set. @@ -288,7 +290,9 @@ G_DEFINE_TYPE_WITH_PRIVATE (MamanBar, maman_bar, G_TYPE_OBJECT) It is important to note that object construction cannot ever fail. If you require a fallible GObject construction, you can use the - GInitable and GAsyncInitable interfaces provided by the GIO library + GInitable and + GAsyncInitable + interfaces provided by the GIO library. @@ -364,7 +368,8 @@ bar_class_init (MamanBarClass *klass) more simply, using the constructed() class method available since GLib 2.12. Note that the constructed() virtual function will only be invoked after the properties marked as - G_PARAM_CONSTRUCT_ONLY or G_PARAM_CONSTRUCT have been consumed, but + G_PARAM_CONSTRUCT_ONLYs or + G_PARAM_CONSTRUCT have been consumed, but before the regular properties passed to g_object_new() have been set. @@ -485,7 +490,7 @@ maman_bar_init (MamanBar *self); - + Non-virtual public methods @@ -509,7 +514,7 @@ maman_bar_do_action (MamanBar *self, /* parameters */) - + Virtual public methods @@ -570,9 +575,10 @@ maman_bar_do_action (MamanBar *self, /* parameters */) Please, note that it is possible for you to provide a default implementation for this class method in the object's class_init function: initialize the - klass->do_action field to a pointer to the actual implementation. + klass->do_action field to a pointer to the + actual implementation. By default, class methods that are not inherited are initialized to - NULL, and thus are to be considered "pure virtual". + NULL, and thus are to be considered "pure virtual". static void maman_bar_real_do_action_two (MamanBar *self, /* parameters */) @@ -622,12 +628,13 @@ maman_bar_do_action_two (MamanBar *self, /* parameters */) - + Virtual private Methods - These are very similar to Virtual Public methods. They just don't - have a public function to call the function directly. The header + These are very similar to virtual + public methods. They just don't + have a public function to call directly. The header file contains only a declaration of the virtual function: /* declaration in maman-bar.h. */ @@ -745,8 +752,8 @@ maman_bar_subtype_class_init (MamanBarSubTypeClass *klass) is used to access the original parent class structure. Its input is a pointer to the class of the derived object and it returns a pointer to the original parent class structure. Instead of using this function - directly, though, you should use the parent_class - pointer created and initialized for us by the G_DEFINE_TYPE_* family of + directly, though, use the parent_class + pointer created and initialized by the G_DEFINE_TYPE_* family of macros, for instance: static void @@ -932,9 +939,9 @@ GType maman_baz_get_type (void); The second step is to implement MamanBaz by defining - its GType. Instead of using - G_DEFINE_TYPE - we use + its GType. Instead of using + G_DEFINE_TYPE, + use G_DEFINE_TYPE_WITH_CODE and the G_IMPLEMENT_INTERFACE @@ -1016,7 +1023,8 @@ G_DEFINE_INTERFACE (MamanIbar, maman_ibar, MAMAN_TYPE_IBAZ); In the G_DEFINE_INTERFACE call above, the third parameter defines the prerequisite type. This is the GType of either an interface or a class. In this case - the MamanIbaz interface is a prerequisite of the MamanIbar. The code + the MamanIbaz interface is a prerequisite of + MamanIbar. The code below shows how an implementation can implement both interfaces and register their implementations: @@ -1225,10 +1233,11 @@ maman_baz_class_init (MamanBazClass *klass) - In this example MamanDerivedBaz is derived from MamanBaz. Both - implement the MamanIbaz interface. MamanDerivedBaz only implements one - method of the MamanIbaz interface and uses the base class implementation - of the other. + In this example, MamanDerivedBaz is derived from + MamanBaz. Both implement the MamanIbaz + interface. MamanDerivedBaz only implements one method of the + MamanIbaz interface and uses the base class implementation of + the other. static void maman_derived_ibaz_do_action (MamanIbaz *ibaz) @@ -1282,7 +1291,7 @@ maman_derived_baz_init (MamanDerivedBaz *self) - In this example MamanDerivedBaz overides the + In this example MamanDerivedBaz overrides the do_action interface method. In its overridden method it calls the base class implementation of the same interface method. @@ -1365,8 +1374,8 @@ maman_file_write (file, buffer, strlen (buffer)); - The MamanFile signal is registered in the class_init - function: + The MamanFile signal is registered in the + class_init function: file_signals[CHANGED] = g_signal_newv ("changed",