The Glib Object system v0.10.0

Mathieu Lacage


            
          

This article is copyrighted to Mathieu Lacage. Although copying and/or reuse of this document is allowed per the license described below, it would be considered friendly to link to this document rather than make a copy of it and to notify me in case you want to republish this work in paper.

This work may be reproduced and distributed in whole or in part, in any medium, physical or electronic, so as long as this copyright notice remains intact and unchanged on all copies. Commercial redistribution is permitted and encouraged, but you may not redistribute, in whole or in part, under terms more restrictive than those under which you received it. If you redistribute a modified or translated version of this work, you must also make the source code to the modified or translated version available in electronic form without charge. However, mere aggregation as part of a larger work shall not count as a modification for this purpose.

All code examples in this work are placed into the public domain, and may be used, modified and redistributed without restriction.

BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

If you want to help on this document, feel free to send me a patch to the original xml which is available on http://www.gnome.org/~mathieu/.

While I am always happy to answer questions about this document, I am not always the best person these questions should be asked to. In doubt, always mail gtk-devel-list@gnome.org. You can register to this mailing list on http://mail.gnome.org.

I'd like to thank Owen Taylor, Tim Janik and especially James Henstridge for their help on IRC, when I was trying to figure out the why of some of GObject aspects.

Revision History
Revision 0.10.024 September 2004
  • Added the section called “Interface Properties” contributed by Ali Zeeshan (<zeenix at qmail dot com>)

  • Add note about g_type_class_add_private and chain up the sample finalize and dispose handlers, contributed by Sylvain FORET (<foret at rsbs dot anu dot edu dot au>).

The following changes have been contributed by Stefan Kost (<ensonic at sonicpulse dot de>)

Revision 0.9.022 June 2004

Mostly maintainance contributed by Stefan Kost (<ensonic at sonicpulse dot de>)

  • Modify the GType section on instantiable types to make the comparison with C++ idioms more accurate (me). Inspired by questions from (<ensonic at sonicpulse dot de>)

  • Added section about chaining up and remove simple chainup comment (me). Based on an idea and patch by (<ensonic at sonicpulse dot de>)

  • Several minor clarification (<ensonic at sonicpulse dot de>)

  • Link to GLib docs regarding to how to disable dynamic type checks (<ensonic at sonicpulse dot de>)

  • Fixing a few typos (<ensonic at sonicpulse dot de>)

  • Fixing expressions b->parent.parent.g_class->g_type, ((GTypeInstance*)b)->g_class->g_type as pointed out by Stepan Kasal (<kasal at ucw dot cz>)

  • Changed PREFIX_OBJECT_TYPE -> PREFIX_TYPE_OBJECT as suggested by Tommi Komulainen (<tommi dot komulainen at nokia dot com>)

Revision 0.8.020 September 2003
  • Add support for pdf build with Fop thanks to Lorenzo Gil Sanchez <lgs at sicem dot biz>

  • Remove stupid old tags from the source xml to make it docbook-compliant.

  • Fix dia testing in the makefiles

  • Fix sample code in GObject section, thanks to comments from Marek Peteraj <marpet at naex dot sk> and Christophe Fergeau <teuf at gnome dot org>

  • Make the sample code in sample/gobject better.

Revision 0.7.025 July 2003
  • Rephrase a few bits in GSignal sections.

  • Add discussion of the detail parameter to the GSignal sections per suggestion from paolo borelli (<pborelli at katamail dot com>).

Revision 0.6.024 July 2003
  • Fix a major bug in GSignal documentation

  • Fix a few bugs in GObject sample code

  • Remove signal section from Howto GObject section. Rewrite a new standalone signal section and its accompanying sample code.

Revision 0.5.018 July 2003
  • Improve interface sample code: make the instance parameter explicit.

  • Misc fixes/typos from Manuel Zabelt (<manuel dot zabelt at web dot de>)

  • Spelling fixes from Jean-Yves Lefort (<jylfort at brutele dot be>))

  • Add introduction chapter per suggestion from David Turner (<david at freetype dot org>). Move the first section in GType chapter to intoduction chapter as footnote.

  • Add section on interface prerequisites as suggsted by Matthias Clasen (<maclas at gmx dot de>)

Revision 0.4.017 March 2003
  • Spelling fixes and misc comments from Jery Kakol (<jkakol at illumina dot com>).

  • Spelling fixes from Steven Cole (<elenstev at mesatop dot com>).

  • Typo fixes in GType, fix sample code. Add sample code.

  • Fill Section on Howto define an interface.

  • Fill Section on Howto implement an interface.

Revision 0.3.022 February 2003
  • Fill Section on Howto implement a GObject.

  • Misc fixes in GType and GSignal chapters.

Revision 0.2.0cannot remember

Second draft

Revision 0.1.0cannot remember

First draft


Table of Contents

1. Introduction
Data types and programming
Exporting a C API
2. The Glib Dynamic Type System
Copy functions
Conventions
Non-Instantiable non-classed fundamental types
Instantiable classed types: objects
Non-instantiable classed types: Interfaces.
Interface Initialization
Interface Destruction
3. Signals
Closures
C Closures
non-C closures (for the fearless).
Signals
Signal registration
Signal connection
Signal emission
The detail argument
4. GObject: what brings everything together.
Object instanciation
Object memory management
Reference count
Weak References
Reference counts and cycles
Object properties
Accessing multiple properties at once
5. How To ?
How To define and implement a new GObject ?
Boilerplate header code
Boilerplate code
Object Construction
Object Destruction
Object methods
Chaining up
How To define and implement Interfaces ?
How To define Interfaces ?
How To define and implement an implementation of an Interface ?
Interface definition prerequisites
Interface Properties
Howto create and use signals
Simple use of signals
How to provide more flexibility to users ?
How users can abuse signals (and why some think it is good)
6. GObject related tools
Debugging reference count problems
Writing API docs
7. GObject Version Changes
GLib 2.2.x releases
GLib 2.4.x releases
GLib 2.6.x releases
8. GObject performance

List of Figures

1.1.

List of Tables

2.1. GType Instantiation/Finalization
2.2. Interface Initialization
2.3. Interface Finalization
4.1. g_object_new
4.2. g_object_unref