1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                    Copyright (C) 2011-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 high-level API for using Gtk.Builder and 
  32. --  user interface files produced with the GUI builder glade-3. 
  33. -- 
  34. --  Here is how to use this package: 
  35. -- 
  36. --     Step 1: create a Builder and add the XML data, just as you would a 
  37. --             standard Gtk.Builder: 
  38. -- 
  39. --             declare 
  40. --                Builder : Gtkada_Builder; 
  41. --                Error   : GError; 
  42. --             begin 
  43. --                Gtk_New (Builder); 
  44. --                Error := Add_From_File (Builder, Default_Filename); 
  45. -- 
  46. --     Step 2: add calls to "Register_Handler" to associate your handlers 
  47. --             with your callbacks. 
  48. -- 
  49. --                Register_Handler 
  50. --                   (Builder      => Builder, 
  51. --                    Handler_Name => "my_handler_id", 
  52. --                    Handler      => My_Handler'Access); 
  53. -- 
  54. --             Where: 
  55. --              - Builder is your Gtkada_Builder, 
  56. --              - "my_handler_id" is the name of the handler as specified in 
  57. --                  Glade-3, in the "Handler" column of the "Signals" tab for 
  58. --                  your object, 
  59. --              - Handler is your Ada subprogram. 
  60. -- 
  61. --              You will need one call to "Register_Handler" per handler 
  62. --              declared in the Glade-3 interface. If there is one or more 
  63. --              handler declared in Glade-3 which does not have an associated 
  64. --              call to Register_Handler, an ASSERT_FAILURE will be raised by 
  65. --              the Gtk main loop. 
  66. -- 
  67. --              There are multiple way to call Register_Handler, see below. 
  68. -- 
  69. --     Step 3: call Do_Connect. 
  70. -- 
  71. --     Step 4: when the application terminates or all Windows described through 
  72. --             your builder should be closed, call Unref to free memory 
  73. --             associated with the Builder. 
  74. -- 
  75. --  </description> 
  76. --  <group>GUI Builder</group> 
  77.  
  78. pragma Ada_2005; 
  79.  
  80. with Ada.Containers.Hashed_Maps; 
  81. with Ada.Strings.Unbounded; use Ada.Strings.Unbounded; 
  82. with Ada.Strings.Unbounded.Hash; 
  83.  
  84. with Glib.Object; use Glib.Object; 
  85. with Gtk.Builder; 
  86.  
  87. package Gtkada.Builder is 
  88.  
  89.    type Gtkada_Builder_Record is new 
  90.      Gtk.Builder.Gtk_Builder_Record with private; 
  91.    type Gtkada_Builder is access all Gtkada_Builder_Record'Class; 
  92.  
  93.    procedure Gtk_New (Builder : out Gtkada_Builder); 
  94.    procedure Initialize (Builder : access Gtkada_Builder_Record'Class); 
  95.    --  Create a new Gtkada_Builder. 
  96.  
  97.    procedure Do_Connect (Builder : access Gtkada_Builder_Record'Class); 
  98.    --  Activate in the builder callabacks that have been connected using 
  99.    --  calls to Register_Handler functions below. 
  100.  
  101.    -------------------------------------- 
  102.    -- Callbacks working on the Builder -- 
  103.    -------------------------------------- 
  104.  
  105.    --  These callbacks take as parameter the Gtkada_Builder. 
  106.    --  If a "User data" is present in the Glade-3, it will be ignored. 
  107.  
  108.    type Builder_Handler is access procedure 
  109.      (Builder : access Gtkada_Builder_Record'Class); 
  110.  
  111.    type Builder_Return_Handler is access function 
  112.      (User_Data : access Gtkada_Builder_Record'Class) return Boolean; 
  113.  
  114.    procedure Register_Handler 
  115.      (Builder      : access Gtkada_Builder_Record'Class; 
  116.       Handler_Name : String; 
  117.       Handler      : Builder_Handler); 
  118.  
  119.    procedure Register_Handler 
  120.      (Builder      : access Gtkada_Builder_Record'Class; 
  121.       Handler_Name : String; 
  122.       Handler      : Builder_Return_Handler); 
  123.  
  124.    -------------------------------------------------------------- 
  125.    -- Callbacks working on user data specified through Glade-3 -- 
  126.    -------------------------------------------------------------- 
  127.  
  128.    --  Use these registry functions if your signal handler was defined in 
  129.    --  the Glade-3 interface with a "User data". The parameter User_Data 
  130.    --  passed to the handlers corresponds to the object entered in the 
  131.    --  "User data" column in Glade-3. 
  132.  
  133.    type Object_Handler is access procedure 
  134.      (User_Data : access GObject_Record'Class); 
  135.  
  136.    type Object_Return_Handler is access function 
  137.      (User_Data : access GObject_Record'Class) return Boolean; 
  138.  
  139.    procedure Register_Handler 
  140.      (Builder      : access Gtkada_Builder_Record'Class; 
  141.       Handler_Name : String; 
  142.       Handler      : Object_Handler); 
  143.  
  144.    procedure Register_Handler 
  145.      (Builder      : access Gtkada_Builder_Record'Class; 
  146.       Handler_Name : String; 
  147.       Handler      : Object_Return_Handler); 
  148.  
  149. private 
  150.  
  151.    type Handler_Type is (Object, Object_Return, Builder, Builder_Return); 
  152.    type Universal_Marshaller (T : Handler_Type) is record 
  153.       case T is 
  154.          when Object => 
  155.             The_Object_Handler : Object_Handler; 
  156.          when Object_Return => 
  157.             The_Object_Return_Handler : Object_Return_Handler; 
  158.          when Builder => 
  159.             The_Builder_Handler : Builder_Handler; 
  160.          when Builder_Return => 
  161.             The_Builder_Return_Handler : Builder_Return_Handler; 
  162.       end case; 
  163.    end record; 
  164.  
  165.    type Universal_Marshaller_Access is access Universal_Marshaller; 
  166.  
  167.    package Handlers_Map is new Ada.Containers.Hashed_Maps 
  168.      (Key_Type        => Unbounded_String, 
  169.       Element_Type    => Universal_Marshaller_Access, 
  170.       Hash            => Ada.Strings.Unbounded.Hash, 
  171.       Equivalent_Keys => "=", 
  172.       "="             => "="); 
  173.  
  174.    type Gtkada_Builder_Record is new 
  175.      Gtk.Builder.Gtk_Builder_Record 
  176.    with record 
  177.       Handlers : Handlers_Map.Map; 
  178.    end record; 
  179.  
  180. end Gtkada.Builder;