1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-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. --  Accelerator maps are used to define runtime configurable accelerators. 
  26. --  Functions for manipulating them are are usually used by higher level 
  27. --  convenience mechanisms like Gtk.UI_Manager.Gtk_UI_Manager and are thus 
  28. --  considered "low-level". You'll want to use them if you're manually creating 
  29. --  menus that should have user-configurable accelerators. 
  30. -- 
  31. --  Accelerator is uniquely defined by: 
  32. -- 
  33. --  
  34. -- 
  35. --     * accelerator path 
  36. -- 
  37. --     * accelerator key 
  38. -- 
  39. --     * accelerator modifiers 
  40. -- 
  41. --  The accelerator path must consist of 
  42. --  "<WINDOWTYPE>/Category1/Category2/.../Action", where WINDOWTYPE should be a 
  43. --  unique application-specific identifier that corresponds to the kind of 
  44. --  window the accelerator is being used in, e.g. "Gimp-Image", 
  45. --  "Abiword-Document" or "Gnumeric-Settings". The "Category1/.../Action" 
  46. --  portion is most appropriately chosen by the action the accelerator 
  47. --  triggers, i.e. for accelerators on menu items, choose the item's menu path, 
  48. --  e.g. "File/Save As", "Image/View/Zoom" or "Edit/Select All". So a full 
  49. --  valid accelerator path may look like: "<Gimp-Toolbox>/File/Dialogs/Tool 
  50. --  Options...". 
  51. -- 
  52. --  All accelerators are stored inside one global Gtk.Accel_Map.Gtk_Accel_Map 
  53. --  that can be obtained using Gtk.Accel_Map.Get. See <link 
  54. --  linkend="monitoring-changes">Monitoring changes</link> for additional 
  55. --  details. 
  56. -- 
  57. --  == Manipulating accelerators == 
  58. -- 
  59. --  New accelerators can be added using Gtk.Accel_Map.Add_Entry. To search for 
  60. --  specific accelerator, use Gtk.Accel_Map.Lookup_Entry. Modifications of 
  61. --  existing accelerators should be done using Gtk.Accel_Map.Change_Entry. 
  62. -- 
  63. --  In order to avoid having some accelerators changed, they can be locked 
  64. --  using Gtk.Accel_Map.Lock_Path. Unlocking is done using 
  65. --  Gtk.Accel_Map.Unlock_Path. 
  66. -- 
  67. --  == Saving and loading accelerator maps == 
  68. -- 
  69. --  Accelerator maps can be saved to and loaded from some external resource. 
  70. --  For simple saving and loading from file, Gtk.Accel_Map.Save and 
  71. --  Gtk.Accel_Map.Load are provided. Saving and loading can also be done by 
  72. --  providing file descriptor to Gtk.Accel_Map.Save_Fd and 
  73. --  Gtk.Accel_Map.Load_Fd. 
  74. -- 
  75. --  == Monitoring changes == 
  76. -- 
  77. --  Gtk.Accel_Map.Gtk_Accel_Map object is only useful for monitoring changes 
  78. --  of accelerators. By connecting to Gtk.Accel_Map.Gtk_Accel_Map::changed 
  79. --  signal, one can monitor changes of all accelerators. It is also possible to 
  80. --  monitor only single accelerator path by using it as a detail of the 
  81. --  Gtk.Accel_Map.Gtk_Accel_Map::changed signal. 
  82. -- 
  83. -- 
  84. --  </description> 
  85. pragma Ada_2005; 
  86.  
  87. pragma Warnings (Off, "*is already use-visible*"); 
  88. with Gdk.Types;       use Gdk.Types; 
  89. with Glib;            use Glib; 
  90. with Glib.Object;     use Glib.Object; 
  91. with Gtk.Accel_Group; use Gtk.Accel_Group; 
  92.  
  93. package Gtk.Accel_Map is 
  94.  
  95.    type Gtk_Accel_Map_Record is new GObject_Record with null record; 
  96.    type Gtk_Accel_Map is access all Gtk_Accel_Map_Record'Class; 
  97.  
  98.    --------------- 
  99.    -- Callbacks -- 
  100.    --------------- 
  101.  
  102.    type Gtk_Accel_Map_Foreach is access procedure 
  103.      (Accel_Path : UTF8_String; 
  104.       Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  105.       Accel_Mods : Gdk.Types.Gdk_Modifier_Type; 
  106.       Changed    : Boolean); 
  107.    --  "accel_path": Accel path of the current accelerator 
  108.    --  "accel_key": Key of the current accelerator 
  109.    --  "accel_mods": Modifiers of the current accelerator 
  110.    --  "changed": Changed flag of the accelerator (if True, accelerator has 
  111.    --  changed during runtime and would need to be saved during an accelerator 
  112.    --  dump) 
  113.  
  114.    ------------------ 
  115.    -- Constructors -- 
  116.    ------------------ 
  117.  
  118.    function Get_Type return Glib.GType; 
  119.    pragma Import (C, Get_Type, "gtk_accel_map_get_type"); 
  120.  
  121.    ------------- 
  122.    -- Methods -- 
  123.    ------------- 
  124.  
  125.    procedure Foreach (Foreach_Func : Gtk_Accel_Map_Foreach); 
  126.    --  Loops over the entries in the accelerator map whose accel path doesn't 
  127.    --  match any of the filters added with Gtk.Accel_Map.Add_Filter, and 
  128.    --  execute Foreach_Func on each. The signature of Foreach_Func is that of 
  129.    --  Gtk_Accel_Map_Foreach, the Changed parameter indicates whether this 
  130.    --  accelerator was changed during runtime (thus, would need saving during 
  131.    --  an accelerator map dump). 
  132.    --  "foreach_func": function to be executed for each accel map entry which 
  133.    --  is not filtered out 
  134.  
  135.    generic 
  136.       type User_Data_Type (<>) is private; 
  137.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  138.    package Foreach_User_Data is 
  139.  
  140.       type Gtk_Accel_Map_Foreach is access procedure 
  141.         (Data       : User_Data_Type; 
  142.          Accel_Path : UTF8_String; 
  143.          Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  144.          Accel_Mods : Gdk.Types.Gdk_Modifier_Type; 
  145.          Changed    : Boolean); 
  146.       --  "data": User data passed to Gtk.Accel_Map.Foreach or 
  147.       --  gtk_accel_map_foreach_unfiltered 
  148.       --  "accel_path": Accel path of the current accelerator 
  149.       --  "accel_key": Key of the current accelerator 
  150.       --  "accel_mods": Modifiers of the current accelerator 
  151.       --  "changed": Changed flag of the accelerator (if True, accelerator has 
  152.       --  changed during runtime and would need to be saved during an accelerator 
  153.       --  dump) 
  154.  
  155.       procedure Foreach 
  156.          (Data         : User_Data_Type; 
  157.           Foreach_Func : Gtk_Accel_Map_Foreach); 
  158.       --  Loops over the entries in the accelerator map whose accel path 
  159.       --  doesn't match any of the filters added with Gtk.Accel_Map.Add_Filter, 
  160.       --  and execute Foreach_Func on each. The signature of Foreach_Func is 
  161.       --  that of Gtk_Accel_Map_Foreach, the Changed parameter indicates 
  162.       --  whether this accelerator was changed during runtime (thus, would need 
  163.       --  saving during an accelerator map dump). 
  164.       --  "data": data to be passed into Foreach_Func 
  165.       --  "foreach_func": function to be executed for each accel map entry 
  166.       --  which is not filtered out 
  167.  
  168.    end Foreach_User_Data; 
  169.  
  170.    procedure Foreach_Unfiltered (Foreach_Func : Gtk_Accel_Map_Foreach); 
  171.    --  Loops over all entries in the accelerator map, and execute Foreach_Func 
  172.    --  on each. The signature of Foreach_Func is that of Gtk_Accel_Map_Foreach, 
  173.    --  the Changed parameter indicates whether this accelerator was changed 
  174.    --  during runtime (thus, would need saving during an accelerator map dump). 
  175.    --  "foreach_func": function to be executed for each accel map entry 
  176.  
  177.    generic 
  178.       type User_Data_Type (<>) is private; 
  179.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  180.    package Foreach_Unfiltered_User_Data is 
  181.  
  182.       type Gtk_Accel_Map_Foreach is access procedure 
  183.         (Data       : User_Data_Type; 
  184.          Accel_Path : UTF8_String; 
  185.          Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  186.          Accel_Mods : Gdk.Types.Gdk_Modifier_Type; 
  187.          Changed    : Boolean); 
  188.       --  "data": User data passed to Gtk.Accel_Map.Foreach or 
  189.       --  Gtk.Accel_Map.Foreach_Unfiltered 
  190.       --  "accel_path": Accel path of the current accelerator 
  191.       --  "accel_key": Key of the current accelerator 
  192.       --  "accel_mods": Modifiers of the current accelerator 
  193.       --  "changed": Changed flag of the accelerator (if True, accelerator has 
  194.       --  changed during runtime and would need to be saved during an accelerator 
  195.       --  dump) 
  196.  
  197.       procedure Foreach_Unfiltered 
  198.          (Data         : User_Data_Type; 
  199.           Foreach_Func : Gtk_Accel_Map_Foreach); 
  200.       --  Loops over all entries in the accelerator map, and execute 
  201.       --  Foreach_Func on each. The signature of Foreach_Func is that of 
  202.       --  Gtk_Accel_Map_Foreach, the Changed parameter indicates whether this 
  203.       --  accelerator was changed during runtime (thus, would need saving 
  204.       --  during an accelerator map dump). 
  205.       --  "data": data to be passed into Foreach_Func 
  206.       --  "foreach_func": function to be executed for each accel map entry 
  207.  
  208.    end Foreach_Unfiltered_User_Data; 
  209.  
  210.    --------------- 
  211.    -- Functions -- 
  212.    --------------- 
  213.  
  214.    procedure Add_Entry 
  215.       (Accel_Path : UTF8_String; 
  216.        Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  217.        Accel_Mods : Gdk.Types.Gdk_Modifier_Type); 
  218.    --  Registers a new accelerator with the global accelerator map. This 
  219.    --  function should only be called once per Accel_Path with the canonical 
  220.    --  Accel_Key and Accel_Mods for this path. To change the accelerator during 
  221.    --  runtime programatically, use Gtk.Accel_Map.Change_Entry. 
  222.    --  Set Accel_Key and Accel_Mods to 0 to request a removal of the 
  223.    --  accelerator. 
  224.    --  Note that Accel_Path string will be stored in a Glib.GQuark. Therefore, 
  225.    --  if you pass a static string, you can save some memory by interning it 
  226.    --  first with g_intern_static_string. 
  227.    --  "accel_path": valid accelerator path 
  228.    --  "accel_key": the accelerator key 
  229.    --  "accel_mods": the accelerator modifiers 
  230.  
  231.    procedure Add_Filter (Filter_Pattern : UTF8_String); 
  232.    --  Adds a filter to the global list of accel path filters. 
  233.    --  Accel map entries whose accel path matches one of the filters are 
  234.    --  skipped by Gtk.Accel_Map.Foreach. 
  235.    --  This function is intended for GTK+ modules that create their own menus, 
  236.    --  but don't want them to be saved into the applications accelerator map 
  237.    --  dump. 
  238.    --  "filter_pattern": a pattern (see Gpattern.Spec.Gpattern_Spec) 
  239.  
  240.    function Change_Entry 
  241.       (Accel_Path : UTF8_String; 
  242.        Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  243.        Accel_Mods : Gdk.Types.Gdk_Modifier_Type; 
  244.        Replace    : Boolean) return Boolean; 
  245.    --  Changes the Accel_Key and Accel_Mods currently associated with 
  246.    --  Accel_Path. Due to conflicts with other accelerators, a change may not 
  247.    --  always be possible, Replace indicates whether other accelerators may be 
  248.    --  deleted to resolve such conflicts. A change will only occur if all 
  249.    --  conflicts could be resolved (which might not be the case if conflicting 
  250.    --  accelerators are locked). Successful changes are indicated by a True 
  251.    --  return value. 
  252.    --  Note that Accel_Path string will be stored in a Glib.GQuark. Therefore, 
  253.    --  if you pass a static string, you can save some memory by interning it 
  254.    --  first with g_intern_static_string. 
  255.    --  "accel_path": a valid accelerator path 
  256.    --  "accel_key": the new accelerator key 
  257.    --  "accel_mods": the new accelerator modifiers 
  258.    --  "replace": True if other accelerators may be deleted upon conflicts 
  259.  
  260.    function Get return Gtk_Accel_Map; 
  261.    --  Gets the singleton global Gtk.Accel_Map.Gtk_Accel_Map object. This 
  262.    --  object is useful only for notification of changes to the accelerator map 
  263.    --  via the ::changed signal; it isn't a parameter to the other accelerator 
  264.    --  map functions. 
  265.    --  Since: gtk+ 2.4 
  266.  
  267.    procedure Load (File_Name : UTF8_String); 
  268.    --  Parses a file previously saved with Gtk.Accel_Map.Save for accelerator 
  269.    --  specifications, and propagates them accordingly. 
  270.    --  "file_name": a file containing accelerator specifications, in the GLib 
  271.    --  file name encoding 
  272.  
  273.    procedure Load_Fd (Fd : Gint); 
  274.    --  Filedescriptor variant of Gtk.Accel_Map.Load. 
  275.    --  Note that the file descriptor will not be closed by this function. 
  276.    --  "fd": a valid readable file descriptor 
  277.  
  278.    procedure Lock_Path (Accel_Path : UTF8_String); 
  279.    --  Locks the given accelerator path. If the accelerator map doesn't yet 
  280.    --  contain an entry for Accel_Path, a new one is created. 
  281.    --  Locking an accelerator path prevents its accelerator from being changed 
  282.    --  during runtime. A locked accelerator path can be unlocked by 
  283.    --  Gtk.Accel_Map.Unlock_Path. Refer to Gtk.Accel_Map.Change_Entry for 
  284.    --  information about runtime accelerator changes. 
  285.    --  If called more than once, Accel_Path remains locked until 
  286.    --  Gtk.Accel_Map.Unlock_Path has been called an equivalent number of times. 
  287.    --  Note that locking of individual accelerator paths is independent from 
  288.    --  locking the Gtk.Accel_Group.Gtk_Accel_Group containing them. For runtime 
  289.    --  accelerator changes to be possible, both the accelerator path and its 
  290.    --  Gtk.Accel_Group.Gtk_Accel_Group have to be unlocked. 
  291.    --  Since: gtk+ 2.4 
  292.    --  "accel_path": a valid accelerator path 
  293.  
  294.    procedure Lookup_Entry 
  295.       (Accel_Path : UTF8_String; 
  296.        Key        : out Gtk.Accel_Group.Gtk_Accel_Key; 
  297.        Found      : out Boolean); 
  298.    --  Looks up the accelerator entry for Accel_Path and fills in Key. 
  299.    --  "accel_path": a valid accelerator path 
  300.    --  "key": the accelerator key to be filled in (optional) 
  301.  
  302.    procedure Save (File_Name : UTF8_String); 
  303.    --  Saves current accelerator specifications (accelerator path, key and 
  304.    --  modifiers) to File_Name. The file is written in a format suitable to be 
  305.    --  read back in by Gtk.Accel_Map.Load. 
  306.    --  "file_name": the name of the file to contain accelerator 
  307.    --  specifications, in the GLib file name encoding 
  308.  
  309.    procedure Save_Fd (Fd : Gint); 
  310.    --  Filedescriptor variant of Gtk.Accel_Map.Save. 
  311.    --  Note that the file descriptor will not be closed by this function. 
  312.    --  "fd": a valid writable file descriptor 
  313.  
  314.    procedure Unlock_Path (Accel_Path : UTF8_String); 
  315.    --  Undoes the last call to Gtk.Accel_Map.Lock_Path on this Accel_Path. 
  316.    --  Refer to Gtk.Accel_Map.Lock_Path for information about accelerator path 
  317.    --  locking. 
  318.    --  Since: gtk+ 2.4 
  319.    --  "accel_path": a valid accelerator path 
  320.  
  321.    ------------- 
  322.    -- Signals -- 
  323.    ------------- 
  324.  
  325.    type Cb_Gtk_Accel_Map_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void is not null access procedure 
  326.      (Self       : access Gtk_Accel_Map_Record'Class; 
  327.       Accel_Path : UTF8_String; 
  328.       Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  329.       Accel_Mods : Gdk.Types.Gdk_Modifier_Type); 
  330.  
  331.    type Cb_GObject_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void is not null access procedure 
  332.      (Self       : access Glib.Object.GObject_Record'Class; 
  333.       Accel_Path : UTF8_String; 
  334.       Accel_Key  : Gdk.Types.Gdk_Key_Type; 
  335.       Accel_Mods : Gdk.Types.Gdk_Modifier_Type); 
  336.  
  337.    Signal_Changed : constant Glib.Signal_Name := "changed"; 
  338.    procedure On_Changed 
  339.       (Self  : not null access Gtk_Accel_Map_Record; 
  340.        Call  : Cb_Gtk_Accel_Map_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void; 
  341.        After : Boolean := False); 
  342.    procedure On_Changed 
  343.       (Self  : not null access Gtk_Accel_Map_Record; 
  344.        Call  : Cb_GObject_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void; 
  345.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  346.        After : Boolean := False); 
  347.    --  Notifies of a change in the global accelerator map. The path is also 
  348.    --  used as the detail for the signal, so it is possible to connect to 
  349.    --  changed::<replaceable>accel_path</replaceable>. 
  350.    --  
  351.    --  Callback parameters: 
  352.    --    --  "accel_path": the path of the accelerator that changed 
  353.    --    --  "accel_key": the key value for the new accelerator 
  354.    --    --  "accel_mods": the modifier mask for the new accelerator 
  355.  
  356. end Gtk.Accel_Map;