1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                  Copyright (C) 2010-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. --  Gtk.Builder - Build an interface from an XML UI definition as produced by 
  31. --  the Glade-3 GUI builder. 
  32. -- 
  33. --  Note that GtkAda provides a higher-level API for using the GUI builder, 
  34. --  in Gtkada.Builder. 
  35. -- 
  36. --  A Gtk_Builder is an auxiliary object that reads textual descriptions of a 
  37. --  user interface and instantiates the described objects. To pass a 
  38. --  description to a Gtk_Builder, call Add_From_File or Add_From_String. 
  39. --  These subprograms can be called multiple times; the builder merges the 
  40. --  content of all descriptions. 
  41. -- 
  42. --  A Gtk_Builder holds a reference to all objects that it has constructed and 
  43. --  drops these references when it is finalized. This finalization can cause 
  44. --  the destruction of non-widget objects or widgets which are not contained 
  45. --  in a toplevel window. For toplevel windows constructed by a builder, it is 
  46. --  the responsibility of the user to call Gtk.Widget.Destroy to get rid of 
  47. --  them and all the widgets they contain. 
  48. -- 
  49. --  The subprograms Get_Object and Get_Widget can be used to access the widgets 
  50. --  in the interface by the names assigned to them inside the UI description. 
  51. --  Toplevel windows returned by this subprogram will stay around until the 
  52. --  user explicitly destroys them with Gtk.Widget.Destroy. 
  53. --  Other widgets will either be part of a larger hierarchy constructed by 
  54. --  the builder (in which case you should not have to worry about their 
  55. --  lifecycle), or without a parent, in which case they have to be added 
  56. --  to some container to make use of them. Non-widget objects need to be 
  57. --  reffed with Glib.Object.Ref to keep them beyond the lifespan of the 
  58. --  builder. 
  59. -- 
  60. --  The subprogram Connect_Signals_Full can be used to connect handlers to the 
  61. --  named signals in the description. 
  62. --  </description> 
  63. --  <group>GUI Builder</group> 
  64. --  <c_version>2.16.6</c_version> 
  65.  
  66. with System; 
  67. with Interfaces.C.Strings; 
  68.  
  69. with Glib; 
  70. with Glib.Error; 
  71. with Glib.Object; 
  72. with Glib.Properties; 
  73.  
  74. with Gtk.Widget; 
  75.  
  76. package Gtk.Builder is 
  77.  
  78.    type Gtk_Builder_Record is new Glib.Object.GObject_Record with private; 
  79.    type Gtk_Builder is access all Gtk_Builder_Record'Class; 
  80.  
  81.    function Get_Type return GType; 
  82.  
  83.    procedure Gtk_New (Builder : out Gtk_Builder); 
  84.    procedure Initialize (Builder : access Gtk_Builder_Record'Class); 
  85.    --  Creates a new Gtk_Builder object. 
  86.  
  87.    function Error_Quark return GQuark; 
  88.  
  89.    function Add_From_File 
  90.      (Builder  : access Gtk_Builder_Record; 
  91.       Filename : String) 
  92.       return Glib.Error.GError; 
  93.    --  Parses a file containing a Gtk_Builder UI definition and merges it with 
  94.    --  the current contents of builder. 
  95.    --  Returns: A GError if an error occured, otherwise null. 
  96.  
  97.    function Add_From_String 
  98.      (Builder : access Gtk_Builder_Record; 
  99.       Buffer  : String; 
  100.       Length  : Gsize) 
  101.       return Glib.Error.GError; 
  102.    --  Parses a string containing a Gtk_Builder UI definition and merges it 
  103.    --  with the current contents of Builder. 
  104.    --  Returns: A GError if an error occured, otherwise null. 
  105.  
  106.    function Get_Object 
  107.      (Builder     : access Gtk_Builder_Record; 
  108.       Object_Name : String) 
  109.       return Glib.Object.GObject; 
  110.    --  Gets the object named Object_Name. Note that this function does not 
  111.    --  increment the reference count of the returned object.  Returns null 
  112.    --  if it could not be found in the object tree. 
  113.    --  See also Get_Widget below. 
  114.  
  115.    function Get_Widget 
  116.      (Builder : access Gtk_Builder_Record; 
  117.       Name    : String) return Gtk.Widget.Gtk_Widget; 
  118.    --  Utility function to retrieve a widget created by Builder. 
  119.    --  Returns null if no widget was found with the given name. 
  120.  
  121.    ------------------------ 
  122.    -- Connecting signals -- 
  123.    ------------------------ 
  124.  
  125.    --  The following is a low-level binding to Gtk+. 
  126.    -- 
  127.    --  You should not need to use this directly. Instead, use a 
  128.    --  Gtkada.Builder.Gtkada_Builder and use the procedures Register_Handler 
  129.    --  to connect your callbacks to signals defined in the GUI builder. 
  130.  
  131.    type Gtk_Builder_Connect_Func is access procedure 
  132.      (Builder        : System.Address; 
  133.       Object         : System.Address; 
  134.       Signal_Name    : Interfaces.C.Strings.chars_ptr; 
  135.       Handler_Name   : Interfaces.C.Strings.chars_ptr; 
  136.       Connect_Object : System.Address; 
  137.       Flags          : Glib.G_Connect_Flags; 
  138.       User_Data      : System.Address); 
  139.    pragma Convention (C, Gtk_Builder_Connect_Func); 
  140.    --  This is the signature of a subprogram used to connect signals. It is 
  141.    --  used by the Connect_Signals and Connect_Signals_Full methods. 
  142.    -- 
  143.    --  Parameters: 
  144.    --     Builder:        The address of a Gtk_Builder 
  145.    --     Object:         The object to connect a signal to 
  146.    --     Signal_Name:    The name of the signal 
  147.    --     Handler_Name:   The name of the handler 
  148.    --     Connect_Object: The internal address of a GObject 
  149.    --     Flags:          G_Connect_Flags to use 
  150.    --     User_Data:      user data 
  151.  
  152.    procedure Connect_Signals_Full 
  153.      (Builder         : access Gtk_Builder_Record; 
  154.       Signal_Function : Gtk_Builder_Connect_Func; 
  155.       User_Data       : System.Address); 
  156.    --  This function can be thought of the interpreted language binding 
  157.    --  version of Connect_Signals, except that it does not require GModule 
  158.    --  to function correctly. 
  159.  
  160.    ---------------- 
  161.    -- Properties -- 
  162.    ---------------- 
  163.  
  164.    --  <properties> 
  165.    --  Name:  Translation_Domain_Property 
  166.    --  Type:  String 
  167.    --  Descr: The translation domain used by gettext 
  168.    -- 
  169.    --  </properties> 
  170.  
  171.    Translation_Domain_Property : constant Glib.Properties.Property_String; 
  172.  
  173. private 
  174.  
  175.    type Gtk_Builder_Record is new Glib.Object.GObject_Record with null record; 
  176.  
  177.    Translation_Domain_Property : constant Glib.Properties.Property_String := 
  178.      Glib.Properties.Build ("translation-domain"); 
  179.  
  180.    pragma Import (C, Error_Quark, "gtk_builder_error_quark"); 
  181.    pragma Import (C, Get_Type, "gtk_builder_get_type"); 
  182.  
  183. end Gtk.Builder;