/src/wrappers/gtk/library/gtk_object.e
Specman e | 170 lines | 60 code | 31 blank | 79 comment | 2 complexity | 8579b7259aa8a3a1dfb2f922f90ca190 MD5 | raw file
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