Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gtk::Object Class Reference

A GtkObject C++ wrapper class. More...

#include <xfc/gtk/object.hh>

Inheritance diagram for Xfc::Gtk::Object:

Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable Xfc::Gtk::Adjustment Xfc::Gtk::CellRenderer Xfc::Gtk::FileFilter Xfc::Gtk::Tooltips Xfc::Gtk::TreeViewColumn Xfc::Gtk::Widget Xfc::Gtk::CellRendererPixbuf Xfc::Gtk::CellRendererProgress Xfc::Gtk::CellRendererText Xfc::Gtk::CellRendererToggle Xfc::Gtk::Calendar Xfc::Gtk::CellView Xfc::Gtk::Container Xfc::Gtk::DrawingArea Xfc::Gtk::Entry Xfc::Gtk::Invisible Xfc::Gtk::Misc Xfc::Gtk::ProgressBar Xfc::Gtk::Range Xfc::Gtk::Ruler Xfc::Gtk::Separator List of all members.

Signal Prototypes

Public Member Functions

Accessors
Methods
Signal Proxies

Detailed Description

A GtkObject C++ wrapper class.

Object is the base class for all widgets, and for a few non-widget objects such as Adjustment. Object predates G::Object; non-widgets that derive from Gtk::Object rather than G::Object do so for backward compatibility reasons. The most interesting difference between Gtk::Object and G::Object is the "floating" reference count. A G::Object is created with a reference count of 1, owned by the creator of the G::Object. (The owner of a reference is the code section that has the right to call G::Object::unref() in order to remove that reference.) A Gtk::Object is created with a reference count of 1 also, but it isn't owned by anyone. Calling G::Object::unref() on the newly-created Gtk::Object is incorrect. Instead, the initial reference count of a Gtk::Object is "floating". The floating reference can be removed by anyone at any time, by calling sink(). Sinking an object does nothing if the object is already sunk (has no floating reference).

When you add a widget to its parent container, the parent GTK+ container will do this:

 g_object_ref (G_OBJECT (child_widget));
 gtk_object_sink (GTK_OBJECT (child_widget));
This means that the container now owns a reference to the child widget (since it called g_object_ref()), and the child widget has no floating reference. If you want to hold onto a reference to the child widget you would have to reference then sink the child widget yourself. In XFC, Gtk::Object::ref() does this for you, by sinking any widget with a floating reference.

The purpose of the floating reference is to keep the child widget alive until you add it to a parent container:

 Gtk::Button *button = new Gtk::Button;
 // button has one floating reference to keep it alive.
 
 container->add(*button);
 // button has one non-floating reference owned by the container.

Gtk::Window is a special case, because GTK+ itself will ref/sink it on creation. That is, after constructing a new Gtk::Window it will have one reference which is owned by GTK+, and is not a floating reference.

One more factor comes into play: the "destroy" signal, emitted by the Gtk::Object::dispose() method. The "destroy" signal asks all code owning a reference to an object to release said reference. So, for example, if you call Gtk::Object::dispose() on a Gtk::Window, GTK+ will release the reference count that it owns; if you call Gtk::Object::dispose() on a Button, then the button will be removed from its parent container and the parent container will release its reference to the button. Because these references are released, calling dispose() should result in freeing all memory associated with an object, unless some buggy code fails to release its references in response to the "destroy" signal. Freeing memory (referred to as finalization) only happens if the reference count reaches zero.

Some simple rules for handling Gtk::Object's:


Constructor & Destructor Documentation

Xfc::Gtk::Object::Object ( GtkObject *  object,
bool  owns_reference = false 
) [explicit, protected]

Construct a new Object from an existing GtkObject.

Parameters:
object A pointer to a GtkObject.
owns_reference Set false if the initial reference count is floating, set true if it's not.
The object can be a newly created GtkObject or an existing GtkObject (see G::Object::Object).

Xfc::Gtk::Object::Object ( GtkObject *  object,
bool  owns_reference = false 
) [explicit, protected]

Construct a new Object from an existing GtkObject.

Parameters:
object A pointer to a GtkObject.
owns_reference Set false if the initial reference count is floating, set true if it's not.
The object can be a newly created GtkObject or an existing GtkObject (see G::Object::Object).


Member Function Documentation

void Xfc::Gtk::Object::sink (  ) 

Removes the floating reference from an object, if it exists; otherwise does nothing.

The ref() method calls this function to sink any object with a floating reference. So as a rule you shouldn't need to call this method at all.

virtual void Xfc::Gtk::Object::ref (  )  [virtual]

Increases the reference count of the object.

This method calls G::Object::ref() first and then sink() to sink the object if it has a floating reference.

Reimplemented from Xfc::G::Object.

virtual void Xfc::Gtk::Object::dispose (  )  [virtual]

Emits the "destroy" signal notifying all reference holders that they should release the object.

See the overview documentation at the top of the page for more details. The memory for the object itself won't be deleted until its reference count actually drops to 0; dispose() merely asks reference holders to release their references, it does not free the object. This method is declared virtual for XFC's use only.

Reimplemented from Xfc::G::Object.


Member Data Documentation

const DestroySignalType Xfc::Gtk::Object::destroy_signal [static, protected]

Destroy signal (see signal_destroy()).

Calls a slot with the signature:

< void function();
<


The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3