Creating a simple GObject class
First, we'll create a very simple GObject called TutGreeter. It has one method, tut_greeter_greet, that writes a friendly greeting on standard output, and one property, greetee that holds the name of the entity to greet.
If you're a git user, you can follow the steps in the tutorial by cloning a repository:
$ git clone https://github.com/skagedal/gobject-introspection-tutorial-code.git tutorial-code $ cd tutorial-code $ git checkout stepone
If you prefer not to use git, you can just copy the files from the links below.
TutGreeter is defined in tut-greeter.h and tut-greeter.c. Most of this is boilerplate GObject code, seen in all GObject C projects, so in this text we'll focus on the interesting bits. This is how the class is initialized:
static void tut_greeter_class_init (TutGreeterClass *klass) { GObjectClass *object_class = G_OBJECT_CLASS (klass); object_class->set_property = tut_greeter_set_property; object_class->get_property = tut_greeter_get_property; object_class->finalize = tut_greeter_finalize; /** * TutGreeter:greetee: * * The entity to greet. */ obj_properties[PROP_GREETEE] = g_param_spec_string ("greetee", "Greetee", "The entity to greet.", "World", G_PARAM_READWRITE | G_PARAM_CONSTRUCT); g_object_class_install_properties (object_class, N_PROPERTIES, obj_properties); g_type_class_add_private (object_class, sizeof (TutGreeterPrivate)); }
This installs a property greetee with the default value of "World". The greet method looks like this:
/** * tut_greeter_greet: * @greeter: a #TutGreeter * * Prints a friendly greeting. * * Return value: nothing. */ void tut_greeter_greet (TutGreeter *greeter) { TutGreeterPrivate *priv; g_return_if_fail (greeter != NULL); priv = TUT_GREETER_GET_PRIVATE (greeter); printf ("Hello, %s!\n", priv->greetee); }
The comments that start with /** are GTK-Doc comments. Everything that is part of the object's external API should be documented with these. This includes functions like tut_greeter_greet, but also properties like TutGreeter:greetee, and macros, structs, enums and signals. See the GTK-Doc manual for detailed information on this.
While documenting external API is always good practice, for introspection to work, it's a necessity. GObject Introspection uses some special annotations in the GTK-Doc markup to figure out how a function is to be used, so that language bindings can map things like output parameters to appropriate constructs.
To test the TutGreeter, we have a simple main function in main.c:
int main (int argc, char *argv[]) { TutGreeter *greeter; greeter = tut_greeter_new (); tut_greeter_greet (greeter); return 0; }
Last, we have a Makefile. In a real-world project, it's preferable to use a more sophisticated build system; the GNU build tool chain with autoconf, automake and friends is the most commonly used and best supported. For the purpose of this tutorial, an ordinary GNU Makefile makes it easy to follow what's happening. Just type make at the console and you should get a binary called greeter. Run it, and feel greeted.
Exercises
Add a new method, tut_greeter_greet_many that should allow you to greet many entities at the same time. Explore various ways of passing a collection of strings using C and GLib data structures.
Keep a log of every greeting made. Add a new method, tut_greeter_get_greet_log that gives access to that log.
To avoid conflicts in the following steps, do the exercies in a separate copy of the code, like a git branch.