This is the base class of the widget hierarchy. Everything in GtkAda inherits from this class Gtk_Object, except for a few structures in the Gdk.* packages (low-level drawing routines).
This class provides a set of handful features that you can choose to reuse in your applications:
Here is a brief explanation on how the reference counting and destruction process work. You should not have to understand all this to use GtkAda, but it might help anyway.
When an object (descendant of Gtk.Object) is created, it has initially a ref_count of 1. A flag is set to say the object is "floating". See the Flags functions in this package for how to retrieve the status of this flag.
When the object gets a parent (ie Gtk.Widget.Set_Parent is called, possibly from other subprograms like Gtk.Container.Add, Gtk.Box.Pack_Start, ...), the ref_count of the object is incremented to 2. If the object was still "floating", it is also "sinked", ie its ref_count is decremented to 1, and the "floating" flag is cleared.
The same behavior as above happens when the object is registered as a top-level widget (i.e. we know it won't have any parent).
Thus the normal life cycle of an object is to have a ref_count to 1, and not be a "floating" object.
When the object is destroyed, the following happens: A temporary reference to the object is created (call to Ref), and ref_count to 2. The object is shutdown: It is removed from its parent (if any), and its ref_count is decremented to 1. The "destroy" signal is emitted, the user's handlers are called, and then all the handlers connected to the object are destroyed. The object is unref-ed. If its ref_count goes down to 0 (normal case), the memory used by the object and its user_data is freed.
Widget Hierarchy |
---|
GObject (see Package_Glib.Object) Gtk_Object (see Package_Gtk.Object) |
Signals |
---|
procedure Handler (Object : access Gtk_Object_Record'Class);
Raised when the object is about to be destroyed. The "destroyed" flag has been set on the object first. Handlers should not keep a reference on the object. Note that when your destroy handlers are called, the user_data is still available. The default implementation destroys all the handlers.
Subprograms |
---|
procedure Sink (Object : access Gtk_Object_Record); | ||
Sink the object. If the object is floating (does not have a parent yet), it is unref-ed once and the floating flag is cleared. | ||
procedure Destroy (Object : access Gtk_Object_Record); | ||
Destroy the object. This emits a "destroy" signal, calls all your handlers, and then unconnects them all. The object is then unref-ed, and if its reference count goes down to 0, the memory associated with the object and its user data is freed. Note that when you destroy handlers are called, the user_data is still available. | ||
function Get_Type return Gtk.Gtk_Type; | ||
Return the internal value associated with a Gtk_Object internally. | ||
function Get_Type (Object : access Gtk_Object_Record) return Gtk_Type; | ||
This function is now obsolete, and is temporarily kept for backward compatibility only. Use Glib.Object.Get_Type instead. ??? | ||
Flags | ||
Each object is associated with a set of flags, that reports the state of the object. The following flags are known by all objects:
| ||
function Flags (Object : access Gtk_Object_Record) return Guint32; | ||
Return the flags that are set for the object, as a binary mask. | ||
procedure Set_Flags (Object : access Gtk_Object_Record; Flags : Guint32); | ||
Set some specific flags for the object. Flags is a mask that will be added to the current flags of the object. | ||
procedure Unset_Flags (Object : access Gtk_Object_Record; Flags : Guint32); | ||
Unset some specific flags for the object. Flags is a mask that will be deleted from the current flags of the object. | ||
function Flag_Is_Set (Object : access Gtk_Object_Record; Flag : Guint32) return Boolean; | ||
Return True if the specific flag Flag is set for the object. | ||
function In_Destruction_Is_Set (Object : access Gtk_Object_Record'Class) return Boolean; | ||
Test if the Destroyed flag is set for the object. | ||
function Floating_Is_Set (Object : access Gtk_Object_Record'Class) return Boolean; | ||
Test if the Floating flag is set for the object. |