1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --                     Copyright (C) 2011-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. -- 
  26. --  This package provides a high-level API for using Gtk.Builder and 
  27. --  user interface files produced with the GUI builder glade-3. 
  28. -- 
  29. --  Here is how to use this package: 
  30. -- 
  31. --     Step 1: create a Builder and add the XML data, just as you would a 
  32. --             standard Gtk.Builder: 
  33. -- 
  34. --             declare 
  35. --                Builder : Gtkada_Builder; 
  36. --                Error   : GError; 
  37. --             begin 
  38. --                Gtk_New (Builder); 
  39. --                Error := Add_From_File (Builder, Default_Filename); 
  40. -- 
  41. --     Step 2: add calls to "Register_Handler" to associate your handlers 
  42. --             with your callbacks. 
  43. -- 
  44. --                Register_Handler 
  45. --                   (Builder      => Builder, 
  46. --                    Handler_Name => "my_handler_id", 
  47. --                    Handler      => My_Handler'Access); 
  48. -- 
  49. --             Where: 
  50. --              - Builder is your Gtkada_Builder, 
  51. --              - "my_handler_id" is the name of the handler as specified in 
  52. --                  Glade-3, in the "Handler" column of the "Signals" tab for 
  53. --                  your object, 
  54. --              - Handler is your Ada subprogram. 
  55. -- 
  56. --              You will need one call to "Register_Handler" per handler 
  57. --              declared in the Glade-3 interface. If there is one or more 
  58. --              handler declared in Glade-3 which does not have an associated 
  59. --              call to Register_Handler, an ASSERT_FAILURE will be raised by 
  60. --              the Gtk main loop. 
  61. -- 
  62. --              There are multiple way to call Register_Handler, see below. 
  63. -- 
  64. --     Step 3: call Do_Connect. 
  65. -- 
  66. --     Step 4: when the application terminates or all Windows described through 
  67. --             your builder should be closed, call Unref to free memory 
  68. --             associated with the Builder. 
  69. -- 
  70. --  </description> 
  71. --  <group>GUI Builder</group> 
  72.  
  73. with Ada.Containers.Hashed_Maps; 
  74. with Ada.Strings.Unbounded; use Ada.Strings.Unbounded; 
  75. with Ada.Strings.Unbounded.Hash; 
  76.  
  77. with Glib.Object; use Glib.Object; 
  78. with Gtk.Builder; 
  79.  
  80. package Gtkada.Builder is 
  81.  
  82.    type Gtkada_Builder_Record is new 
  83.      Gtk.Builder.Gtk_Builder_Record with private; 
  84.    type Gtkada_Builder is access all Gtkada_Builder_Record'Class; 
  85.  
  86.    procedure Gtk_New (Builder : out Gtkada_Builder); 
  87.    procedure Initialize (Builder : access Gtkada_Builder_Record'Class); 
  88.    --  Create a new Gtkada_Builder. 
  89.  
  90.    procedure Do_Connect (Builder : access Gtkada_Builder_Record'Class); 
  91.    --  Activate in the builder callabacks that have been connected using 
  92.    --  calls to Register_Handler functions below. 
  93.  
  94.    -------------------------------------- 
  95.    -- Callbacks working on the Builder -- 
  96.    -------------------------------------- 
  97.  
  98.    --  These callbacks take as parameter the Gtkada_Builder. 
  99.    --  If a "User data" is present in the Glade-3, it will be ignored. 
  100.  
  101.    type Builder_Handler is access procedure 
  102.      (Builder : access Gtkada_Builder_Record'Class); 
  103.  
  104.    type Builder_Return_Handler is access function 
  105.      (User_Data : access Gtkada_Builder_Record'Class) return Boolean; 
  106.  
  107.    procedure Register_Handler 
  108.      (Builder      : access Gtkada_Builder_Record'Class; 
  109.       Handler_Name : String; 
  110.       Handler      : Builder_Handler); 
  111.  
  112.    procedure Register_Handler 
  113.      (Builder      : access Gtkada_Builder_Record'Class; 
  114.       Handler_Name : String; 
  115.       Handler      : Builder_Return_Handler); 
  116.  
  117.    -------------------------------------------------------------- 
  118.    -- Callbacks working on user data specified through Glade-3 -- 
  119.    -------------------------------------------------------------- 
  120.  
  121.    --  Use these registry functions if your signal handler was defined in 
  122.    --  the Glade-3 interface with a "User data". The parameter User_Data 
  123.    --  passed to the handlers corresponds to the object entered in the 
  124.    --  "User data" column in Glade-3. 
  125.  
  126.    type Object_Handler is access procedure 
  127.      (User_Data : access GObject_Record'Class); 
  128.  
  129.    type Object_Return_Handler is access function 
  130.      (User_Data : access GObject_Record'Class) return Boolean; 
  131.  
  132.    procedure Register_Handler 
  133.      (Builder      : access Gtkada_Builder_Record'Class; 
  134.       Handler_Name : String; 
  135.       Handler      : Object_Handler); 
  136.  
  137.    procedure Register_Handler 
  138.      (Builder      : access Gtkada_Builder_Record'Class; 
  139.       Handler_Name : String; 
  140.       Handler      : Object_Return_Handler); 
  141.  
  142. private 
  143.  
  144.    type Handler_Type is (Object, Object_Return, Builder, Builder_Return); 
  145.    type Universal_Marshaller (T : Handler_Type) is record 
  146.       case T is 
  147.          when Object => 
  148.             The_Object_Handler : Object_Handler; 
  149.          when Object_Return => 
  150.             The_Object_Return_Handler : Object_Return_Handler; 
  151.          when Builder => 
  152.             The_Builder_Handler : Builder_Handler; 
  153.          when Builder_Return => 
  154.             The_Builder_Return_Handler : Builder_Return_Handler; 
  155.       end case; 
  156.    end record; 
  157.  
  158.    type Universal_Marshaller_Access is access Universal_Marshaller; 
  159.  
  160.    package Handlers_Map is new Ada.Containers.Hashed_Maps 
  161.      (Key_Type        => Unbounded_String, 
  162.       Element_Type    => Universal_Marshaller_Access, 
  163.       Hash            => Ada.Strings.Unbounded.Hash, 
  164.       Equivalent_Keys => "=", 
  165.       "="             => "="); 
  166.  
  167.    type Gtkada_Builder_Record is new 
  168.      Gtk.Builder.Gtk_Builder_Record 
  169.    with record 
  170.       Handlers : Handlers_Map.Map; 
  171.    end record; 
  172.  
  173. end Gtkada.Builder;