Line 0
Link Here
|
|
|
1 |
----------------------------------------------------------------------- |
2 |
-- GtkAda - Ada95 binding for Gtk+/Gnome -- |
3 |
-- -- |
4 |
-- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet -- |
5 |
-- Copyright (C) 2000-2011, AdaCore -- |
6 |
-- -- |
7 |
-- This library is free software; you can redistribute it and/or -- |
8 |
-- modify it under the terms of the GNU General Public -- |
9 |
-- License as published by the Free Software Foundation; either -- |
10 |
-- version 2 of the License, or (at your option) any later version. -- |
11 |
-- -- |
12 |
-- This library is distributed in the hope that it will be useful, -- |
13 |
-- but WITHOUT ANY WARRANTY; without even the implied warranty of -- |
14 |
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- |
15 |
-- General Public License for more details. -- |
16 |
-- -- |
17 |
-- You should have received a copy of the GNU General Public -- |
18 |
-- License along with this library; if not, write to the -- |
19 |
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- |
20 |
-- Boston, MA 02111-1307, USA. -- |
21 |
-- -- |
22 |
-- As a special exception, if other files instantiate generics from -- |
23 |
-- this unit, or you link this unit with other files to produce an -- |
24 |
-- executable, this unit does not by itself cause the resulting -- |
25 |
-- executable to be covered by the GNU General Public License. This -- |
26 |
-- exception does not however invalidate any other reasons why the -- |
27 |
-- executable file might be covered by the GNU Public License. -- |
28 |
----------------------------------------------------------------------- |
29 |
|
30 |
-- <description> |
31 |
-- This is the base class of the widget hierarchy. |
32 |
-- Everything in GtkAda inherits from this class Gtk_Object, except for a few |
33 |
-- structures in the Gdk.* packages (low-level drawing routines). |
34 |
-- |
35 |
-- This class provides a set of handful features that you can choose to reuse |
36 |
-- in your applications: |
37 |
-- |
38 |
-- - Reference counting: an object is not deleted while there exists at least |
39 |
-- one reference to it. Although GtkAda mostly takes care of that aspect |
40 |
-- transparently, you might need in some obscure cases to increment or |
41 |
-- decrement the reference counting for a widget manually, so that it is not |
42 |
-- removed from memory while you still need it. |
43 |
-- |
44 |
-- - User data: any number of data can be attached to a Gtk_Object or one of |
45 |
-- its children. Theses data are referenced by a String, in a hash-table. |
46 |
-- GtkAda itself uses this feature to provide an easy conversion between C |
47 |
-- and Ada widgets. |
48 |
-- Although you might prefer to have a completely object-oriented |
49 |
-- application (and thus associate data through class inheritance), it |
50 |
-- might be convenient to directly attach some data to your objects. |
51 |
-- |
52 |
-- - It also contains the basic structures and subprograms required for signal |
53 |
-- emission. This is of course used to implement the signal mechanism in |
54 |
-- GtkAda itself, but can also be used to implement a Model/View/Controller |
55 |
-- framework. |
56 |
-- |
57 |
-- Note that a lot of functions provided in the C interface are not provided |
58 |
-- here. They are used to emulate an object-oriented language in C, which can |
59 |
-- of course be done much more conveniently in Ada. Therefore most of these |
60 |
-- functions are not needed. |
61 |
-- |
62 |
-- Here is a brief explanation on how the reference counting and destruction |
63 |
-- process work. You should not have to understand all this to use GtkAda, but |
64 |
-- it might help anyway. |
65 |
-- |
66 |
-- When an object (descendant of Gtk.Object) is created, it has initially a |
67 |
-- ref_count of 1. A flag is set to say the object is "floating". See the |
68 |
-- Flags functions in this package for how to retrieve the status of this |
69 |
-- flag. |
70 |
-- |
71 |
-- When the object gets a parent (ie Gtk.Widget.Set_Parent is called, possibly |
72 |
-- from other subprograms like Gtk.Container.Add, Gtk.Box.Pack_Start, ...), |
73 |
-- the ref_count of the object is incremented to 2. |
74 |
-- If the object was still "floating", it is also "sinked", ie its ref_count |
75 |
-- is decremented to 1, and the "floating" flag is cleared. |
76 |
-- |
77 |
-- The same behavior as above happens when the object is registered as a |
78 |
-- top-level widget (i.e. we know it won't have any parent). |
79 |
-- |
80 |
-- Thus the normal life cycle of an object is to have a ref_count to 1, and |
81 |
-- not be a "floating" object. |
82 |
-- |
83 |
-- When the object is destroyed, the following happens: |
84 |
-- A temporary reference to the object is created (call to Ref), and |
85 |
-- ref_count to 2. |
86 |
-- The object is shutdown: |
87 |
-- It is removed from its parent (if any), and its ref_count is |
88 |
-- decremented to 1. |
89 |
-- The "destroy" signal is emitted, the user's handlers are called, |
90 |
-- and then all the handlers connected to the object are destroyed. |
91 |
-- The object is unref-ed. If its ref_count goes down to 0 (normal case), |
92 |
-- the memory used by the object and its user_data is freed. |
93 |
-- |
94 |
-- </description> |
95 |
-- <c_version>2.8.17</c_version> |
96 |
-- <group>Abstract base classes</group> |
97 |
|
98 |
with Glib.Object; |
99 |
with Glib.Properties; |
100 |
with Glib.GSlist; |
101 |
with Gtkada.Types; |
102 |
|
103 |
package Gtk.Object is |
104 |
|
105 |
type Gtk_Object_Record is new Glib.Object.GObject_Record with private; |
106 |
type Gtk_Object is access all Gtk_Object_Record'Class; |
107 |
|
108 |
procedure Destroy (Object : access Gtk_Object_Record); |
109 |
-- Destroy the object. |
110 |
-- This emits a "destroy" signal, calls all your handlers, and then |
111 |
-- unconnects them all. The object is then unref-ed, and if its reference |
112 |
-- count goes down to 0, the memory associated with the object and its |
113 |
-- user data is freed. |
114 |
-- Note that when you destroy handlers are called, the user_data is still |
115 |
-- available. |
116 |
-- |
117 |
-- When a widget is destroyed, it will break any references it holds to |
118 |
-- other objects. If the widget is inside a container, the widget will be |
119 |
-- removed from the container. If the widget is a toplevel (derived from |
120 |
-- Gtk_Window), it will be removed from the list of toplevels, and the |
121 |
-- reference GTK+ holds to it will be removed. Removing widget from its |
122 |
-- container or the list of toplevels results in the widget being |
123 |
-- finalized, unless you've added additional references to the widget with |
124 |
-- Ref. |
125 |
-- |
126 |
-- In most cases, only toplevel widgets (windows) require explicit |
127 |
-- destruction, because when you destroy a toplevel its children will be |
128 |
-- destroyed as well. |
129 |
|
130 |
function Get_Type return Gtk.Gtk_Type; |
131 |
-- Return the internal value associated with a Gtk_Object internally. |
132 |
pragma Import (C, Get_Type, "gtk_object_get_type"); |
133 |
|
134 |
function Get_Type (Object : access Gtk_Object_Record) return Gtk_Type; |
135 |
-- This function is now obsolete, and is temporarily kept for backward |
136 |
-- compatibility only. Use Glib.Object.Get_Type instead. |
137 |
-- ??? |
138 |
|
139 |
----------- |
140 |
-- Lists -- |
141 |
----------- |
142 |
|
143 |
function Convert (W : Gtk_Object) return System.Address; |
144 |
function Convert (W : System.Address) return Gtk_Object; |
145 |
|
146 |
package Object_SList is new Glib.GSlist.Generic_SList (Gtk_Object); |
147 |
|
148 |
----------- |
149 |
-- Flags -- |
150 |
----------- |
151 |
-- Each object is associated with a set of flags, that reports the state |
152 |
-- of the object. |
153 |
-- The following flags are known by all objects: |
154 |
-- |
155 |
-- - "Destroyed": |
156 |
-- Set if the object is marked as destroyed (if its reference count is |
157 |
-- not yet 0, the memory has not been freed, but you should not use it |
158 |
-- anyway). |
159 |
-- |
160 |
-- - "Floating": |
161 |
-- The object has no parent yet, since it was just created. Its |
162 |
-- reference count is still 1 (as it was initially). This flag is |
163 |
-- cleared as soon as Set_Parent is called on the widget or the widget |
164 |
-- is qualified as a toplevel widget (see |
165 |
-- Gtk.Container.Register_Toplevel). |
166 |
|
167 |
In_Destruction : constant := 2 ** 0; |
168 |
Floating : constant := 2 ** 1; |
169 |
Reserved_1 : constant := 2 ** 2; |
170 |
Reserved_2 : constant := 2 ** 3; |
171 |
|
172 |
function Flags (Object : access Gtk_Object_Record) return Guint32; |
173 |
-- Return the flags that are set for the object, as a binary mask. |
174 |
|
175 |
procedure Set_Flags (Object : access Gtk_Object_Record; Flags : Guint32); |
176 |
-- Set some specific flags for the object. |
177 |
-- Flags is a mask that will be added to the current flags of the object. |
178 |
|
179 |
procedure Unset_Flags (Object : access Gtk_Object_Record; Flags : Guint32); |
180 |
-- Unset some specific flags for the object. |
181 |
-- Flags is a mask that will be deleted from the current flags of the |
182 |
-- object. |
183 |
|
184 |
function Flag_Is_Set |
185 |
(Object : access Gtk_Object_Record; Flag : Guint32) return Boolean; |
186 |
-- Return True if the specific flag Flag is set for the object. |
187 |
|
188 |
function In_Destruction_Is_Set |
189 |
(Object : access Gtk_Object_Record'Class) return Boolean; |
190 |
-- Test if the Destroyed flag is set for the object. |
191 |
|
192 |
-- <doc_ignore> |
193 |
function Destroyed_Is_Set (Object : access Gtk_Object_Record'Class) |
194 |
return Boolean renames In_Destruction_Is_Set; |
195 |
-- backward compatibility only |
196 |
-- </doc_ignore> |
197 |
|
198 |
function Floating_Is_Set |
199 |
(Object : access Gtk_Object_Record'Class) return Boolean; |
200 |
-- Test if the Floating flag is set for the object. |
201 |
|
202 |
-------------------------- |
203 |
-- Creating new widgets -- |
204 |
-------------------------- |
205 |
|
206 |
-- <doc_ignore> |
207 |
-- The following definitions are only provided for better backward |
208 |
-- compatibility. You should use Glib.Object directly. |
209 |
|
210 |
subtype GObject_Class is Glib.Object.GObject_Class; |
211 |
Uninitialized_Class : GObject_Class renames |
212 |
Glib.Object.Uninitialized_Class; |
213 |
|
214 |
subtype Signal_Parameter_Types is Glib.Object.Signal_Parameter_Types; |
215 |
|
216 |
Null_Parameter_Types : Signal_Parameter_Types renames |
217 |
Glib.Object.Null_Parameter_Types; |
218 |
|
219 |
procedure Initialize_Class_Record |
220 |
(Object : access GObject_Record'Class; |
221 |
Signals : Gtkada.Types.Chars_Ptr_Array; |
222 |
Class_Record : in out GObject_Class; |
223 |
Type_Name : String; |
224 |
Parameters : Signal_Parameter_Types := Null_Parameter_Types) |
225 |
renames Glib.Object.Initialize_Class_Record; |
226 |
|
227 |
-- </doc_ignore> |
228 |
|
229 |
--------------- |
230 |
-- User Data -- |
231 |
--------------- |
232 |
-- It is possible to associate your own specific data with an existing |
233 |
-- object. See the documentation in Glib.Object. |
234 |
-- The declaration below has been kept for compatibility reasons. |
235 |
|
236 |
generic |
237 |
package User_Data renames Glib.Object.User_Data; |
238 |
|
239 |
----------------- |
240 |
-- Obsolescent -- |
241 |
----------------- |
242 |
-- All subprograms below are now obsolescent in gtk+. They might be removed |
243 |
-- from future versions of gtk+ (and therefore GtkAda). |
244 |
-- To find out whether your code uses any of these, we recommend compiling |
245 |
-- with the -gnatwj switch |
246 |
-- <doc_ignore> |
247 |
|
248 |
procedure Sink (Object : access Gtk_Object_Record); |
249 |
pragma Obsolescent (Sink); |
250 |
-- Sink the object. |
251 |
-- If the object is floating (does not have a parent yet), it is unref-ed |
252 |
-- once and the floating flag is cleared. |
253 |
|
254 |
-- </doc_ignore> |
255 |
|
256 |
---------------- |
257 |
-- Properties -- |
258 |
---------------- |
259 |
|
260 |
-- <properties> |
261 |
-- The following properties are defined for this widget. See |
262 |
-- Glib.Properties for more information on properties. |
263 |
-- |
264 |
-- - Name: User_Data_Property |
265 |
-- Type: Pointer |
266 |
-- Flags: read-write |
267 |
-- Descr: Anonymous User Data Pointer |
268 |
-- See also: User_Data.Set, using the default Id "user_data" |
269 |
-- |
270 |
-- </properties> |
271 |
|
272 |
User_Data_Property : constant Glib.Properties.Property_Address; |
273 |
|
274 |
------------- |
275 |
-- Signals -- |
276 |
------------- |
277 |
|
278 |
-- <signals> |
279 |
-- The following new signals are defined for this widget: |
280 |
-- |
281 |
-- - "destroy" |
282 |
-- procedure Handler (Object : access Gtk_Object_Record'Class); |
283 |
-- |
284 |
-- Raised when the object is about to be destroyed. The "destroyed" |
285 |
-- flag has been set on the object first. Handlers should not keep |
286 |
-- a reference on the object. |
287 |
-- Note that when your destroy handlers are called, the user_data is |
288 |
-- still available. |
289 |
-- The default implementation destroys all the handlers. |
290 |
-- </signals> |
291 |
|
292 |
Signal_Destroy : constant Glib.Signal_Name := "destroy"; |
293 |
|
294 |
private |
295 |
type Gtk_Object_Record is new Glib.Object.GObject_Record with null record; |
296 |
|
297 |
User_Data_Property : constant Glib.Properties.Property_Address := |
298 |
Glib.Properties.Build ("user_data"); |
299 |
|
300 |
pragma Inline (Floating_Is_Set); |
301 |
pragma Inline (In_Destruction_Is_Set); |
302 |
|
303 |
end Gtk.Object; |
304 |
|
305 |
-- The following subprograms never had a binding, but are now obsolescent |
306 |
-- No binding: gtk_object_add_arg_type |
307 |
-- No binding: gtk_object_get |
308 |
-- No binding: gtk_object_get_data |
309 |
-- No binding: gtk_object_get_data_by_id |
310 |
-- No binding: gtk_object_get_user_data |
311 |
-- No binding: gtk_object_new |
312 |
-- No binding: gtk_object_ref |
313 |
-- No binding: gtk_object_unref |
314 |
-- No binding: gtk_object_remove_data |
315 |
-- No binding: gtk_object_remove_data_by_id |
316 |
-- No binding: gtk_object_remove_no_notify |
317 |
-- No binding: gtk_object_remove_no_notify_by_id |
318 |
-- No binding: gtk_object_set |
319 |
-- No binding: gtk_object_set_data |
320 |
-- No binding: gtk_object_set_data_by_id |
321 |
-- No binding: gtk_object_set_data_by_id_full |
322 |
-- No binding: gtk_object_set_data_full |
323 |
-- No binding: gtk_object_set_user_data |
324 |
-- No binding: gtk_object_weakref |
325 |
-- No binding: gtk_object_weakunref |