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