/src/wrappers/gtk/library/gtk_object.e

  1indexing
  2	copyright: "[
  3					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  4					
  5					This library is free software; you can redistribute it and/or
  6					modify it under the terms of the GNU Lesser General Public License
  7					as published by the Free Software Foundation; either version 2.1 of
  8					the License, or (at your option) any later version.
  9					
 10					This library is distributed in the hope that it will be useful, but
 11					WITHOUT ANY WARRANTY; without even the implied warranty of
 12					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 13					Lesser General Public License for more details.
 14
 15					You should have received a copy of the GNU Lesser General Public
 16					License along with this library; if not, write to the Free Software
 17					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 18					02110-1301 USA
 19				]"
 20	date: "$Date:$"
 21	revision "$REvision:$"
 22
 23deferred class GTK_OBJECT
 24	-- GtkObject is the base class for all widgets, and for a few
 25	-- non-widget objects such as GtkAdjustment. GtkObject predates
 26	-- GObject; non-widgets that derive from GtkObject rather than
 27	-- GObject do so for backward compatibility reasons.
 28	
 29	-- The most interesting difference between GtkObject and GObject is
 30	-- the "floating" reference count. A GObject is created with a
 31	-- reference count of 1, owned by the creator of the GObject. (The
 32	-- owner of a reference is the code section that has the right to
 33	-- call g_object_unref() in order to remove that reference.) A
 34	-- GtkObject is created with a reference count of 1 also, but it
 35	-- isn't owned by anyone; calling g_object_unref() on the
 36	-- newly-created GtkObject is incorrect. Instead, the initial
 37	-- reference count of a GtkObject is "floating". The floating
 38	-- reference can be removed by anyone at any time, by calling
 39	-- gtk_object_sink(). gtk_object_sink() does nothing if an object
 40	-- is already sunk (has no floating reference).
 41
 42	-- When you add a widget to its parent container, the parent
 43	-- container will do this:
 44	
 45	-- child_widget.ref; child_widget.sink
 46
 47	-- This means that the container now owns a reference to the child
 48	-- widget (since it called `ref'), and the child widget has no
 49	-- floating reference.
 50
 51	-- The purpose of the floating reference is to keep the child
 52	-- widget alive until you add it to a parent container:
 53	
 54	-- create button.make -- button has one floating reference to keep
 55	-- it alive container.add(button) -- button has one non-floating
 56	-- reference owned by the container
 57
 58	-- GtkWindow is a special case, because GTK+ itself will ref/sink
 59	-- it on creation. That is, after calling `make,' the GtkWindow
 60	-- will have one reference which is owned by GTK+, and no floating
 61	-- references.
 62
 63	-- One more factor comes into play: the "destroy" signal, emitted
 64	-- by the `destroy' method. The "destroy" signal asks all code
 65	-- owning a reference to an object to release said reference. So,
 66	-- for example, if you call `destroy' on a GtkWindow, GTK+ will
 67	-- release the reference count that it owns; if you call `destroy'
 68	-- on a GtkButton, then the button will be removed from its parent
 69	-- container and the parent container will release its reference to
 70	-- the button. Because these references are released, calling
 71	-- `destroy' should result in freeing all memory associated with an
 72	-- object, unless some buggy code fails to release its references
 73	-- in response to the "destroy" signal. Freeing memory (referred to
 74	-- as finalization only happens if the reference count reaches
 75	-- zero.
 76
 77	-- Some simple rules for handling GtkObject:
 78
 79	-- * Never call `unref' unless you have previously called `ref'
 80	--   even if you created the GtkObject. (Note: this is not true for
 81	--   GObject; for GObject, the creator of the object owns a
 82	--   reference.)
 83
 84	-- * Call `destroy' to get rid of most objects in most cases. In
 85	--   particular, widgets are almost always destroyed in this way.
 86
 87	-- * Because of the floating reference count, you don't need to
 88	--   worry about reference counting for widgets and toplevel
 89	--   windows, unless you explicitly call `ref' yourself.
 90
 91inherit
 92	G_OBJECT
 93		-- undefine make
 94		redefine store_eiffel_wrapper
 95		end
 96
 97insert
 98	GTK -- that provides the gtk singleton.
 99	GTK_OBJECT_EXTERNALS
100
101feature
102	sink  is
103			-- Removes the floating reference from a GtkObject, if it exists;
104			-- otherwise does nothing. See the GtkObject overview documentation at
105			-- the top of the page.
106		do
107			gtk_object_sink (handle)
108		end
109
110	destroy is
111			-- Emits the "destroy" signal notifying all reference holders that they
112			-- should release the GtkObject. See the overview documentation at the
113			-- top of the page for more details.  The memory for the object itself
114			-- won't be deleted until its reference count actually drops to 0;
115			-- destroy merely asks reference holders to release their references,
116			-- it does not free the object.
117		do
118			gtk_object_destroy (handle)
119		end
120
121	store_eiffel_wrapper is
122		do
123			Precursor
124			ref -- This takes care of sinking the object and/or adding a reference
125		end
126
127feature -- Signals
128	-- The "destroy" signal
129
130	-- void user_function (GtkObject *object, gpointer user_data);
131
132	-- Signals that all holders of a reference to the GtkObject should
133	-- release the reference that they hold. May result in finalization
134	-- of the object if all references are released.
135	
136	-- object : 	the object which received the signal.
137	-- user_data : 	user data set when the signal handler was connected.
138
139	connect_to_destroy_signal,
140	connect_agent_to_destroy_signal (a_procedure: PROCEDURE[TUPLE[GTK_OBJECT]]) is
141			-- Connect `a_procedure' but invokes the fixed
142			-- `destroy_callback' special feature."
143		local destroy_callback: DESTROY_CALLBACK
144		do
145			create destroy_callback.make
146			destroy_callback.connect (Current, a_procedure)
147			-- The above is just a shorter version of 
148			-- create destroy_callback.make
149			-- destroy_callback.connect (Current, a_procedure)
150		end
151	
152	-- TODO: implement a enable_on_destroy and on_destroy
153
154	enable_on_destroy is
155			-- Connects "destroy" signal to `on_destroy' feature.
156		do
157			connect (Current, destroy_signal_name, $on_destroy)
158		end
159
160	on_destroy is
161			-- Called on destroy signals. Redefine it in your heir classes
162		do
163		end
164
165feature {} -- Signal names
166	destroy_signal_name: STRING is "destroy"
167
168invariant
169		gtk_initialized: gtk.is_initialized
170end