1----------------------------------------------------------------------- 2-- GtkAda - Ada95 binding for Gtk+/Gnome -- 3-- -- 4-- Copyright (C) 2001-2013, AdaCore -- 5-- -- 6-- This library is free software; you can redistribute it and/or -- 7-- modify it under the terms of the GNU General Public -- 8-- License as published by the Free Software Foundation; either -- 9-- version 2 of the License, or (at your option) any later version. -- 10-- -- 11-- This library is distributed in the hope that it will be useful, -- 12-- but WITHOUT ANY WARRANTY; without even the implied warranty of -- 13-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- 14-- General Public License for more details. -- 15-- -- 16-- You should have received a copy of the GNU General Public -- 17-- License along with this library; if not, write to the -- 18-- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- 19-- Boston, MA 02111-1307, USA. -- 20-- -- 21-- As a special exception, if other files instantiate generics from -- 22-- this unit, or you link this unit with other files to produce an -- 23-- executable, this unit does not by itself cause the resulting -- 24-- executable to be covered by the GNU General Public License. This -- 25-- exception does not however invalidate any other reasons why the -- 26-- executable file might be covered by the GNU Public License. -- 27----------------------------------------------------------------------- 28 29-- <description> 30-- 31-- This package provides a minimal binding to the GObject type in Glib. 32-- See Glib.Properties for information on how to manipulate properties 33-- 34-- </description> 35-- <group>Glib, the general-purpose library</group> 36 37with Gtkada.Types; 38with Glib.GSlist; 39with Glib.Glist; 40pragma Elaborate_All (Glib.GSlist); 41pragma Elaborate_All (Glib.Glist); 42 43package Glib.Object is 44 45 type GObject_Record is tagged private; 46 type GObject is access all GObject_Record'Class; 47 -- The base type for Glib/Gdk/Gtk objects. It basically gives access 48 -- to an underlying C object. This is not a controlled type for 49 -- efficiency reasons and because glib takes care of the memory 50 -- management on its own. 51 52 function Is_Created (Object : GObject_Record'Class) return Boolean; 53 -- Return True if the associated C object has been created, False if 54 -- no C object is associated with Object. 55 -- This is not the same as testing whether an access type (for instance 56 -- any of the widgets) is "null", since this relates to the underlying 57 -- C object. 58 59 function Get_Type (Object : access GObject_Record) return GType; 60 -- Return the type of Object. 61 -- This function is mostly used internally, since in Ada you can simply 62 -- test whether an object belong to a class with a statement like: 63 -- 64 -- if Object in Gtk_Button_Record'Class then ... 65 -- 66 -- which is easier. 67 68 ---------------- 69 -- Life cycle -- 70 ---------------- 71 72 procedure G_New (Object : out GObject); 73 -- Create a new GObject. 74 -- This is only required when you want to create an Ada tagged type to 75 -- which you can attach new signals. Most of the time, you only need to 76 -- directly create the appropriate Gtk Widget by calling the correct 77 -- Gtk_New procedure. 78 79 procedure Initialize (Object : access GObject_Record'Class); 80 -- Internal initialization function. 81 -- See the section "Creating your own widgets" in the documentation. 82 83 procedure Ref (Object : access GObject_Record); 84 -- Increment the reference counter for Object. See Unref below. 85 -- Since an object is not deleted while its reference count is not null, 86 -- this is a way to keep an object in memory, in particular when you 87 -- want to temporarily remove a widget from its parent. 88 89 procedure Unref (Object : access GObject_Record); 90 -- Decrement the reference counter for Object. When this reaches 0, the 91 -- object is effectively destroy, all the callbacks associated with it are 92 -- disconnected. 93 94 type Weak_Notify is access procedure 95 (Data : System.Address; 96 Where_The_Object_Was : System.Address); 97 pragma Convention (C, Weak_Notify); 98 -- Called when Where_The_Object_Was is destroyed (although you can still 99 -- use this to reset it). Data is the argument passed to Weak_Ref. 100 -- You should destroy and free the memory occupied by Data 101 102 procedure Weak_Ref 103 (Object : access GObject_Record'Class; 104 Notify : Weak_Notify; 105 Data : System.Address := System.Null_Address); 106 -- This kind of reference doesn't increment the object's reference 107 -- counting. However, it can and should be used to monitor the object's 108 -- life cycle, in particular to detect is destruction. 109 -- When Object is destroyed, calls Notify 110 111 procedure Weak_Unref 112 (Object : access GObject_Record'Class; 113 Notify : Weak_Notify; 114 Data : System.Address := System.Null_Address); 115 -- Cancels the settings of Weak_Ref. 116 117 procedure Deallocate (Object : access GObject_Record); 118 -- This operation is used to deallocate Object. 119 -- The default implementation assumes that the value passed in is an 120 -- access value created by an allocator of the default pool, i.e. it 121 -- will assume that an instance of 122 -- Unchecked_Deallocation (GObject_Record'Class, GObject) 123 -- can be used to deallocate the designated object. 124 -- Types derived of GObject_Record can override this operation in order 125 -- to cope with objects allocated on other pools or even objects allocated 126 -- on the stack. 127 -- This design is limited to support only one allocation strategy for each 128 -- class, as the class tag is used to identify the applicable strategy. 129 130 procedure Ref_Sink (Object : access GObject_Record); 131 -- Increase the reference count of Object, and possibly remove the 132 -- floating reference, if Object has a floating reference. 133 -- In other words, if the object is floating, then this call "assumes 134 -- ownership" of the floating reference, converting it to a normal 135 -- reference by clearing the floating flag while leaving the reference 136 -- count unchanged. If the object is not floating, then this call 137 -- adds a new normal reference increasing the reference count by one. 138 139 ------------------------ 140 -- Interfacing with C -- 141 ------------------------ 142 -- The following functions are made public so that one can easily create 143 -- new objects outside the Glib or Gtk package hierarchy. 144 -- Only experienced users should make use of these functions. 145 146 function Get_Object 147 (Object : access GObject_Record'Class) return System.Address; 148 -- Access the underlying C pointer. 149 150 function Get_Object_Or_Null (Object : GObject) return System.Address; 151 -- Same as above, but passing "null" is valid. 152 153 procedure Set_Object 154 (Object : access GObject_Record'Class; 155 Value : System.Address); 156 -- Modify the underlying C pointer. 157 158 function Get_User_Data 159 (Obj : System.Address; 160 Stub : GObject_Record'Class) return GObject; 161 -- Return the Ada object matching the C object Obj. If Obj was created 162 -- explicitely from GtkAda, this will be the exact same widget. If Obj was 163 -- created implicitely by gtk+ (buttons in complex windows,...), a new Ada 164 -- object of type Stub will be created. 165 166 function Get_User_Data_Fast 167 (Obj : System.Address; 168 Stub : GObject_Record'Class) return GObject; 169 -- Same as Get_User_Data, but does not try to guess the type of Obj, 170 -- always default to Stub if Obj is unknown to GtkAda. 171 172 function Unchecked_Cast 173 (Obj : access GObject_Record'Class; 174 Stub : GObject_Record'Class) return GObject; 175 -- Cast Obj in an object of tag Stub'Class. 176 -- Return the resulting object and free the memory pointed by Obj. 177 178 ------------- 179 -- Signals -- 180 ------------- 181 -- Any child of GObject can be associated with any number of signals. The 182 -- mechanism for signals is fully generic, and any number of arguments can 183 -- be associated with signals. 184 -- See the function Initialize_Class_Record for more information on how 185 -- to create new signals for your own new widgets. 186 -- The subprograms below are provided for introspection: they make it 187 -- possible to query the list of signals defined for a specific widget, 188 -- as well as their parameters and return types. 189 190 type Signal_Id_Array is array (Guint range <>) of Glib.Signal_Id; 191 192 type Signal_Query is private; 193 194 function Lookup 195 (Object : Glib.GType; Signal : String) return Glib.Signal_Id; 196 -- Returns the signal Id associated with a specific Object/Signal pair. 197 -- Null_Signal_Id is returned if no such signal exists for Object. 198 -- You can then use the Query procedure to get more information on the 199 -- signal. 200 201 function List_Ids (Typ : Glib.GType) return Signal_Id_Array; 202 -- Return the list of signals defined for Typ. You can get more information 203 -- on each of this signals by using the Query function below. 204 -- See also the function Get_Type above to convert from an object instance 205 -- to its type. Using a GType as the parameter makes it easier to find the 206 -- signals for a widget and its ancestors (using Glib.Parent). 207 208 procedure Query (Id : Glib.Signal_Id; Result : out Signal_Query); 209 -- Return the description associated with the signal Id. You can get the 210 -- various fields from Query with one of the functions below. 211 -- Result is undefined if Id is Invalid_Signal_Id or Null_Signal_Id 212 213 function Id (Q : Signal_Query) return Glib.Signal_Id; 214 -- Return the signal Id. Each Id is specific to a widget/signal name pair. 215 -- These Ids can then be used to temporarily block a signal for instance, 216 -- through the subprograms in Gtk.Handlers. 217 218 function Signal_Name (Q : Signal_Query) return Glib.Signal_Name; 219 -- Return the name of the signal, as should be used in a call to Connect. 220 221 function Return_Type (Q : Signal_Query) return Glib.GType; 222 -- Return the type of object returned by the handlers for this signal. 223 224 function Params (Q : Signal_Query) return GType_Array; 225 -- Return the list of parameters for the handlers for this signal 226 227 -------------------------- 228 -- Creating new widgets -- 229 -------------------------- 230 -- These types and functions are used only when creating new widget types 231 -- directly in Ada. These functions initialize the classes so that they are 232 -- correctly recognized by gtk+ itself 233 -- See the GtkAda user's guide for more information on how to create your 234 -- own widget types in Ada. 235 236 type Interface_Vtable is private; 237 -- The virtual table of an interface (see Glib.Types). This is only useful 238 -- when doing introspection. 239 240 type GObject_Class is new GType_Class; 241 Uninitialized_Class : constant GObject_Class; 242 -- This type encloses all the informations related to a specific type of 243 -- object or widget. All instances of such an object have a pointer to this 244 -- structure, that includes the definition of all the signals that exist 245 -- for a given object, all its properties,... 246 247 type Signal_Parameter_Types is 248 array (Natural range <>, Natural range <>) of GType; 249 -- The description of the parameters for each event. These are the 250 -- parameters that the application must provide when emitting the 251 -- signal. The user can of course add his own parameters when connecting 252 -- the signal in his application, through the use of 253 -- Gtk.Handlers.User_Callback. 254 -- 255 -- Each event defined with Initialize_Class_Record below should have an 256 -- entry in this table. If Gtk_Type_None is found in the table, it is 257 -- ignored. For instance, a Signal_Parameter_Type like: 258 -- (1 => (1 => Gdk_Type_Gdk_Event, 2 => GType_None), 259 -- 2 => (1 => GType_Int, 2 => GType_Int)); 260 -- defines two signals, the first with a single Gdk_Event parameter, the 261 -- second with two ints parameters. 262 263 Null_Parameter_Types : constant Signal_Parameter_Types (1 .. 0, 1 .. 0) := 264 (others => (others => GType_None)); 265 -- An empty array, used as a default parameter in Initialize_Class_Record. 266 267 procedure Initialize_Class_Record 268 (Object : access GObject_Record'Class; 269 Signals : Gtkada.Types.Chars_Ptr_Array; 270 Class_Record : in out GObject_Class; 271 Type_Name : String; 272 Parameters : Signal_Parameter_Types := Null_Parameter_Types); 273 -- Create the class record for a new object type. 274 -- It is associated with Signals'Length new signals. A pointer to the 275 -- newly created structure is also returned in Class_Record. 276 -- If Class_Record /= System.Null_Address, no memory allocation is 277 -- performed, we just reuse it. As a result, each instantiation of an 278 -- object will share the same GObject_Class, exactly as is done for gtk+. 279 -- 280 -- Note: The underlying C object must already have been initialized 281 -- by a call to its parent's Initialize function. 282 -- Parameters'Length should be the same as Signals'Length, or the result 283 -- is undefined. 284 -- As a special case, if Parameters has its default value, all signals are 285 -- created with no argument. This is done for backward compatibility 286 -- mainly, and you should instead give it an explicit value. 287 -- Type_Name should be a unique name identifying the name of the new type. 288 -- 289 -- Only the signals with no parameter can be connected from C code. 290 -- However, any signal can be connected from Ada. This is due to the way 291 -- we define default marshallers for the signals. 292 293 function Type_From_Class (Class_Record : GObject_Class) return GType; 294 -- Return the internal gtk+ type that describes the newly created 295 -- Class_Record. 296 -- See the function Glib.Types.Class_Peek for the opposite function 297 -- converting from a GType to a GObject_Class. 298 299 ------------------------------ 300 -- Properties introspection -- 301 ------------------------------ 302 -- See glib.ads for more information on properties 303 304 function Interface_List_Properties 305 (Vtable : Interface_Vtable) return Glib.Param_Spec_Array; 306 -- Return the list of properties of an interface (see also Glib.Properties) 307 -- from a Vtable from Default_Interface_Peek). 308 -- See also Class_List_Properties for a similar function for objects. 309 310 function Class_List_Properties 311 (Class : GObject_Class) return Glib.Param_Spec_Array; 312 -- Return the list of all properties of the class. 313 314 ------------- 315 -- Signals -- 316 ------------- 317 -- ??? This section is incomplete. 318 319 -- <signals> 320 -- The following new signals are defined for this object: 321 -- 322 -- - "notify" 323 -- procedure Handler 324 -- (Object : access GObject_Record'Class; Name : String); 325 -- 326 -- Emitted when the property Name has been modified 327 -- </signals> 328 329 procedure Notify 330 (Object : access GObject_Record; 331 Property_Name : String); 332 -- Emits the "notify" signal, to signal every listener that the property 333 -- has been changed. 334 335 --------------- 336 -- User_Data -- 337 --------------- 338 -- This package allow you to associate your own Data to the C widgets. No 339 -- type verification is made to check if you are using the correct 340 -- matching Get function. This is your own responsability. 341 -- 342 -- We recommend using this package only if you want your data to be 343 -- available from your own C code. If you just want to access it from Ada, 344 -- you should consider creating a new tagged type instead, that extends 345 -- either GObject_Record or the specific widget type you need. 346 347 -- <doc_ignore> 348 349 generic 350 type Data_Type (<>) is private; 351 package User_Data is 352 type On_Destroyed_Callback is access procedure (Data : Data_Type); 353 -- On_Destroyed is called when the data is overriden in the object, by 354 -- an other object with the same ID, or when the object itself is 355 -- destroyed 356 357 function Get 358 (Object : access GObject_Record'Class; 359 Id : String := "user_data") return Data_Type; 360 -- Get the information associated with the key ID. 361 -- Raise Gtkada.Types.Data_Error if there is none. 362 363 function Get 364 (Object : access GObject_Record'Class; 365 Id : String := "user_data"; 366 Default : Data_Type) return Data_Type; 367 -- Get the information associated with the key ID. 368 -- Return Default instead of raising an exception if there is no such 369 -- user data 370 371 procedure Set 372 (Object : access GObject_Record'Class; 373 Data : Data_Type; 374 Id : String := "user_data"; 375 On_Destroyed : On_Destroyed_Callback := null); 376 -- Associate some new user data with the object. 377 -- The strings starting with "gtkada_" are reserved for GtkAda's 378 -- internal use, please avoid using them. 379 380 procedure Remove 381 (Object : access GObject_Record'Class; Id : String := "user_data"); 382 -- Remove some data from the object 383 384 function Get 385 (Object : access GObject_Record'Class; 386 Id : Glib.GQuark) return Data_Type; 387 function Get 388 (Object : access GObject_Record'Class; 389 Id : Glib.GQuark; 390 Default : Data_Type) return Data_Type; 391 -- Same function as Get above, but uses directly the Quark associated 392 -- with the string, which speeds up the access time significantly. 393 394 procedure Set 395 (Object : access GObject_Record'Class; 396 Data : Data_Type; 397 Id : Glib.GQuark; 398 On_Destroyed : On_Destroyed_Callback := null); 399 -- Same function as Set above, but uses directly the Quark associated 400 -- with the string, which speeds up the access time significantly. 401 402 procedure Remove 403 (Object : access GObject_Record'Class; Id : Glib.GQuark); 404 -- Same function as Remove above, but uses directly the Quark associated 405 -- with the string, which speeds up the access time significantly. 406 407 private 408 -- <doc_ignore> 409 procedure Free_Data (Data : System.Address); 410 -- Internal procedure used to free user data in the package body 411 pragma Convention (C, Free_Data); 412 -- </doc_ignore> 413 end User_Data; 414 415 -- </doc_ignore> 416 417 ----------- 418 -- Lists -- 419 ----------- 420 421 function Convert (W : GObject) return System.Address; 422 function Convert (W : System.Address) return GObject; 423 424 package Object_List is new Glib.GSlist.Generic_SList (GObject); 425 package Object_Simple_List is new Glib.Glist.Generic_List (GObject); 426 427private 428 429 type GObject_Record is tagged record 430 Ptr : System.Address := System.Null_Address; 431 end record; 432 433 type Interface_Vtable is new Glib.C_Proxy; 434 435 Uninitialized_Class : constant GObject_Class := 436 GObject_Class (System.Null_Address); 437 438 type Signal_Query is record 439 Signal_Id : Guint; 440 Signal_Name : System.Address; -- const gchar* 441 IType : GType; 442 Signal_Flags : Gint; -- enum GSignalFlags 443 Return_Type : GType; 444 N_Params : Guint; 445 Param_Types : System.Address; -- const gtype* 446 end record; 447 pragma Convention (C, Signal_Query); 448 449 -- <doc_ignore> 450 451 -- Note: the following functions and types should only be used 452 -- for internal usage, not in the user's applications. 453 -- If you use type inheritance for new widgets, you should not need 454 -- these functions. 455 456 GtkAda_String : constant String := "_GtkAda" & ASCII.NUL; 457 GtkAda_String_Quark : Glib.GQuark := Glib.Unknown_Quark; 458 -- The name for the user data that we set in the objects. 459 -- The Quark version is to speed up the string lookup (this is done 460 -- only once). 461 462 -- </doc_ignore> 463 464 pragma Inline (Get_Object); 465 pragma Inline (Set_Object); 466 pragma Import (C, Type_From_Class, "ada_type_from_class"); 467 pragma Import (C, Query, "g_signal_query"); 468 pragma Import (C, Id, "ada_gsignal_query_id"); 469 pragma Import (C, Return_Type, "ada_gsignal_query_return_type"); 470end Glib.Object; 471