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-2013, 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. -- As a special exception, if other files instantiate generics from  -- 
  23. -- this unit, or you link this unit with other files to produce an   -- 
  24. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  25. -- executable to be covered by the GNU General Public License. This  -- 
  26. -- exception does not however invalidate any other reasons why the   -- 
  27. -- executable file  might be covered by the  GNU Public License.     -- 
  28. ----------------------------------------------------------------------- 
  29.  
  30. --  <description> 
  31. --  This widget provides completion functionality for Gtk.Gentry.Gtk_Entry. 
  32. -- 
  33. --  "Completion functionality" means that when the user modifies the text in 
  34. --  the entry, GtkEntryCompletion checks which rows in the model match the 
  35. --  current content of the entry, and displays a list of matches. By default, 
  36. --  the matching is done by comparing the entry text case-insensitively against 
  37. --  the text column of the model (see Set_Text_Column), but this can be 
  38. --  overridden with a custom match function (see Set_Match_Func). 
  39. -- 
  40. --  When the user selects a completion, the content of the entry is updated. 
  41. --  By default, the content of the entry is replaced by the text column of the 
  42. --  model, but this can be overridden by connecting to the ::match-selected 
  43. --  signal and updating the entry in the signal handler. Note that you should 
  44. --  return TRUE from the signal handler to suppress the default behaviour. 
  45. -- 
  46. --  To add completion functionality to an entry, use Gtk.Entry.Set_Completion. 
  47. -- 
  48. --  In addition to regular completion matches, which will be inserted into the 
  49. --  entry when they are selected, GtkEntryCompletion also allows to display 
  50. --  "actions" in the popup window. Their appearance is similar to menuitems, to 
  51. --  differentiate them clearly from completion strings. When an action is 
  52. --  selected, the ::action-activated signal is emitted. 
  53. -- 
  54. --  </description> 
  55. --  <group>Numeric/Text Data Entry</group> 
  56.  
  57. pragma Warnings (Off, "*is already use-visible*"); 
  58. with Glib;                 use Glib; 
  59. with Glib.Object;          use Glib.Object; 
  60. with Glib.Properties;      use Glib.Properties; 
  61. with Glib.Types;           use Glib.Types; 
  62. with Gtk.Buildable;        use Gtk.Buildable; 
  63. with Gtk.Cell_Layout;      use Gtk.Cell_Layout; 
  64. with Gtk.Tree_Model;       use Gtk.Tree_Model; 
  65. with Gtk.Widget;           use Gtk.Widget; 
  66. with Interfaces.C.Strings; use Interfaces.C.Strings; 
  67.  
  68. package Gtk.Entry_Completion is 
  69.  
  70.    type Gtk_Entry_Completion_Record is new GObject_Record with null record; 
  71.    type Gtk_Entry_Completion is access all Gtk_Entry_Completion_Record'Class; 
  72.  
  73.    type C_Gtk_Entry_Completion_Match_Func is access function 
  74.      (Completion    : System.Address; 
  75.       Key           : Interfaces.C.Strings.chars_ptr; 
  76.       Iter          : Gtk.Tree_Model.Gtk_Tree_Iter; 
  77.       Data          : System.Address) return Boolean; 
  78.    pragma Convention (C, C_Gtk_Entry_Completion_Match_Func); 
  79.  
  80.    ------------------ 
  81.    -- Constructors -- 
  82.    ------------------ 
  83.  
  84.    procedure Gtk_New (Completion : out Gtk_Entry_Completion); 
  85.    procedure Initialize 
  86.       (Completion : access Gtk_Entry_Completion_Record'Class); 
  87.    --  Creates a new Gtk.Entry_Completion.Gtk_Entry_Completion object. 
  88.    --  Since: gtk+ 2.4 
  89.  
  90.    function Get_Type return Glib.GType; 
  91.    pragma Import (C, Get_Type, "gtk_entry_completion_get_type"); 
  92.  
  93.    ------------- 
  94.    -- Methods -- 
  95.    ------------- 
  96.  
  97.    procedure Complete (Completion : access Gtk_Entry_Completion_Record); 
  98.    --  Requests a completion operation, or in other words a refiltering of the 
  99.    --  current list with completions, using the current key. The completion 
  100.    --  list view will be updated accordingly. 
  101.    --  Since: gtk+ 2.4 
  102.  
  103.    procedure Delete_Action 
  104.       (Completion : access Gtk_Entry_Completion_Record; 
  105.        Index      : Gint); 
  106.    --  Deletes the action at Index_ from Completion's action list. 
  107.    --  Since: gtk+ 2.4 
  108.    --  "index_": The index of the item to Delete. 
  109.  
  110.    function Get_Completion_Prefix 
  111.       (Completion : access Gtk_Entry_Completion_Record) return UTF8_String; 
  112.    --  Get the original text entered by the user that triggered the completion 
  113.    --  or null if there's no completion ongoing. 
  114.    --  Since: gtk+ 2.12 
  115.  
  116.    function Get_Entry 
  117.       (Completion : access Gtk_Entry_Completion_Record) 
  118.        return Gtk.Widget.Gtk_Widget; 
  119.    --  Gets the entry Completion has been attached to. 
  120.    --  Since: gtk+ 2.4 
  121.  
  122.    function Get_Inline_Completion 
  123.       (Completion : access Gtk_Entry_Completion_Record) return Boolean; 
  124.    procedure Set_Inline_Completion 
  125.       (Completion        : access Gtk_Entry_Completion_Record; 
  126.        Inline_Completion : Boolean); 
  127.    --  Sets whether the common prefix of the possible completions should be 
  128.    --  automatically inserted in the entry. 
  129.    --  Since: gtk+ 2.6 
  130.    --  "inline_completion": True to do inline completion 
  131.  
  132.    function Get_Inline_Selection 
  133.       (Completion : access Gtk_Entry_Completion_Record) return Boolean; 
  134.    procedure Set_Inline_Selection 
  135.       (Completion       : access Gtk_Entry_Completion_Record; 
  136.        Inline_Selection : Boolean); 
  137.    --  Sets whether it is possible to cycle through the possible completions 
  138.    --  inside the entry. 
  139.    --  Since: gtk+ 2.12 
  140.    --  "inline_selection": True to do inline selection 
  141.  
  142.    function Get_Minimum_Key_Length 
  143.       (Completion : access Gtk_Entry_Completion_Record) return Gint; 
  144.    procedure Set_Minimum_Key_Length 
  145.       (Completion : access Gtk_Entry_Completion_Record; 
  146.        Length     : Gint); 
  147.    --  Requires the length of the search key for Completion to be at least 
  148.    --  length. This is useful for long lists, where completing using a small 
  149.    --  key takes a lot of time and will come up with meaningless results anyway 
  150.    --  (ie, a too large dataset). 
  151.    --  Since: gtk+ 2.4 
  152.    --  "length": The minimum length of the key in order to start completing. 
  153.  
  154.    function Get_Model 
  155.       (Completion : access Gtk_Entry_Completion_Record) 
  156.        return Gtk.Tree_Model.Gtk_Tree_Model; 
  157.    procedure Set_Model 
  158.       (Completion : access Gtk_Entry_Completion_Record; 
  159.        Model      : access Gtk.Tree_Model.Gtk_Tree_Model_Record'Class); 
  160.    --  Sets the model for a Gtk.Entry_Completion.Gtk_Entry_Completion. If 
  161.    --  Completion already has a model set, it will remove it before setting the 
  162.    --  new model. If model is null, then it will unset the model. 
  163.    --  Since: gtk+ 2.4 
  164.    --  "model": The Gtk.Tree_Model.Gtk_Tree_Model. 
  165.  
  166.    function Get_Popup_Completion 
  167.       (Completion : access Gtk_Entry_Completion_Record) return Boolean; 
  168.    procedure Set_Popup_Completion 
  169.       (Completion       : access Gtk_Entry_Completion_Record; 
  170.        Popup_Completion : Boolean); 
  171.    --  Sets whether the completions should be presented in a popup window. 
  172.    --  Since: gtk+ 2.6 
  173.    --  "popup_completion": True to do popup completion 
  174.  
  175.    function Get_Popup_Set_Width 
  176.       (Completion : access Gtk_Entry_Completion_Record) return Boolean; 
  177.    procedure Set_Popup_Set_Width 
  178.       (Completion      : access Gtk_Entry_Completion_Record; 
  179.        Popup_Set_Width : Boolean); 
  180.    --  Sets whether the completion popup window will be resized to be the same 
  181.    --  width as the entry. 
  182.    --  Since: gtk+ 2.8 
  183.    --  "popup_set_width": True to make the width of the popup the same as the 
  184.    --  entry 
  185.  
  186.    function Get_Popup_Single_Match 
  187.       (Completion : access Gtk_Entry_Completion_Record) return Boolean; 
  188.    procedure Set_Popup_Single_Match 
  189.       (Completion         : access Gtk_Entry_Completion_Record; 
  190.        Popup_Single_Match : Boolean); 
  191.    --  Sets whether the completion popup window will appear even if there is 
  192.    --  only a single match. You may want to set this to False if you are using 
  193.    --  <link linkend="GtkEntryCompletion--inline-completion">inline 
  194.    --  completion</link>. 
  195.    --  Since: gtk+ 2.8 
  196.    --  "popup_single_match": True if the popup should appear even for a single 
  197.    --  match 
  198.  
  199.    function Get_Text_Column 
  200.       (Completion : access Gtk_Entry_Completion_Record) return Gint; 
  201.    procedure Set_Text_Column 
  202.       (Completion : access Gtk_Entry_Completion_Record; 
  203.        Column     : Gint); 
  204.    --  completion list with just strings. This function will set up Completion 
  205.    --  to have a list displaying all (and just) strings in the completion list, 
  206.    --  and to get those strings from Column in the model of Completion. This 
  207.    --  functions creates and adds a Gtk.Cellrenderertext.Gtk_Cellrenderertext 
  208.    --  for the selected column. If you need to set the text column, but don't 
  209.    --  want the cell renderer, use g_object_set to set the ::text_column 
  210.    --  property directly. 
  211.    --  Since: gtk+ 2.4 
  212.    --  "column": The column in the model of Completion to get strings from. 
  213.  
  214.    procedure Insert_Action_Markup 
  215.       (Completion : access Gtk_Entry_Completion_Record; 
  216.        Index      : Gint; 
  217.        Markup     : UTF8_String); 
  218.    --  Inserts an action in Completion's action item list at position Index_ 
  219.    --  with markup Markup. 
  220.    --  Since: gtk+ 2.4 
  221.    --  "index_": The index of the item to insert. 
  222.    --  "markup": Markup of the item to insert. 
  223.  
  224.    procedure Insert_Action_Text 
  225.       (Completion : access Gtk_Entry_Completion_Record; 
  226.        Index      : Gint; 
  227.        Text       : UTF8_String); 
  228.    --  Inserts an action in Completion's action item list at position Index_ 
  229.    --  with text Text. If you want the action item to have markup, use 
  230.    --  Gtk.Entry_Completion.Insert_Action_Markup. 
  231.    --  Since: gtk+ 2.4 
  232.    --  "index_": The index of the item to insert. 
  233.    --  "text": Text of the item to insert. 
  234.  
  235.    procedure Insert_Prefix (Completion : access Gtk_Entry_Completion_Record); 
  236.    --  Requests a prefix insertion. 
  237.    --  Since: gtk+ 2.6 
  238.  
  239.    procedure Set_Match_Func 
  240.       (Completion  : access Gtk_Entry_Completion_Record; 
  241.        Func        : C_Gtk_Entry_Completion_Match_Func; 
  242.        Func_Data   : System.Address; 
  243.        Func_Notify : Glib.G_Destroy_Notify_Address); 
  244.    --  Sets the match function for Completion to be Func. The match function 
  245.    --  is used to determine if a row should or should not be in the completion 
  246.    --  list. 
  247.    --  Since: gtk+ 2.4 
  248.    --  "func": The C_Gtk_Entry_Completion_Match_Func to use. 
  249.    --  "func_data": The user data for Func. 
  250.    --  "func_notify": Destroy notifier for Func_Data. 
  251.  
  252.    ---------------------- 
  253.    -- GtkAda additions -- 
  254.    ---------------------- 
  255.  
  256.    generic 
  257.    type Data_Type (<>) is private; 
  258.    package Match_Functions is 
  259.       type Gtk_Entry_Completion_Match_Func is access 
  260.       function (Completion : access Gtk_Entry_Completion_Record'Class; 
  261.          Key        : String; 
  262.          Iter       : Gtk.Tree_Model.Gtk_Tree_Iter; 
  263.          User_Data  : Data_Type) return Boolean; 
  264.  
  265.       type Destroy_Notify is access procedure (Data : in out Data_Type); 
  266.  
  267.       procedure Set_Match_Func 
  268.         (Completion  : access Gtk_Entry_Completion_Record; 
  269.          Func        : Gtk_Entry_Completion_Match_Func; 
  270.          Func_Data   : Data_Type; 
  271.          Func_Notify : Destroy_Notify); 
  272.       --  Sets the match function for completion to be Func. The match function 
  273.       --  is used to determine if a row should or should not be in the 
  274.       --  completion list. 
  275.    end Match_Functions; 
  276.  
  277.    ---------------- 
  278.    -- Interfaces -- 
  279.    ---------------- 
  280.    --  This class implements several interfaces. See Glib.Types 
  281.    -- 
  282.    --  - "Buildable" 
  283.    -- 
  284.    --  - "CellLayout" 
  285.  
  286.    package Implements_Buildable is new Glib.Types.Implements 
  287.      (Gtk.Buildable.Gtk_Buildable, Gtk_Entry_Completion_Record, Gtk_Entry_Completion); 
  288.    function "+" 
  289.      (Widget : access Gtk_Entry_Completion_Record'Class) 
  290.    return Gtk.Buildable.Gtk_Buildable 
  291.    renames Implements_Buildable.To_Interface; 
  292.    function "-" 
  293.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  294.    return Gtk_Entry_Completion 
  295.    renames Implements_Buildable.To_Object; 
  296.  
  297.    package Implements_CellLayout is new Glib.Types.Implements 
  298.      (Gtk.Cell_Layout.Gtk_Cell_Layout, Gtk_Entry_Completion_Record, Gtk_Entry_Completion); 
  299.    function "+" 
  300.      (Widget : access Gtk_Entry_Completion_Record'Class) 
  301.    return Gtk.Cell_Layout.Gtk_Cell_Layout 
  302.    renames Implements_CellLayout.To_Interface; 
  303.    function "-" 
  304.      (Interf : Gtk.Cell_Layout.Gtk_Cell_Layout) 
  305.    return Gtk_Entry_Completion 
  306.    renames Implements_CellLayout.To_Object; 
  307.  
  308.    ---------------- 
  309.    -- Properties -- 
  310.    ---------------- 
  311.    --  The following properties are defined for this widget. See 
  312.    --  Glib.Properties for more information on properties) 
  313.    -- 
  314.    --  Name: Inline_Completion_Property 
  315.    --  Type: Boolean 
  316.    --  Flags: read-write 
  317.    --  Determines whether the common prefix of the possible completions should 
  318.    --  be inserted automatically in the entry. Note that this requires 
  319.    --  text-column to be set, even if you are using a custom match function. 
  320.    -- 
  321.    --  Name: Inline_Selection_Property 
  322.    --  Type: Boolean 
  323.    --  Flags: read-write 
  324.    --  Determines whether the possible completions on the popup will appear in 
  325.    --  the entry as you navigate through them. 
  326.    -- 
  327.    --  Name: Minimum_Key_Length_Property 
  328.    --  Type: Gint 
  329.    --  Flags: read-write 
  330.    -- 
  331.    --  Name: Model_Property 
  332.    --  Type: Gtk.Tree_Model.Gtk_Tree_Model 
  333.    --  Flags: read-write 
  334.    -- 
  335.    --  Name: Popup_Completion_Property 
  336.    --  Type: Boolean 
  337.    --  Flags: read-write 
  338.    --  Determines whether the possible completions should be shown in a popup 
  339.    --  window. 
  340.    -- 
  341.    --  Name: Popup_Set_Width_Property 
  342.    --  Type: Boolean 
  343.    --  Flags: read-write 
  344.    --  Determines whether the completions popup window will be resized to the 
  345.    --  width of the entry. 
  346.    -- 
  347.    --  Name: Popup_Single_Match_Property 
  348.    --  Type: Boolean 
  349.    --  Flags: read-write 
  350.    --  Determines whether the completions popup window will shown for a single 
  351.    --  possible completion. You probably want to set this to False if you are 
  352.    --  using <link linkend="GtkEntryCompletion--inline-completion">inline 
  353.    --  completion</link>. 
  354.    -- 
  355.    --  Name: Text_Column_Property 
  356.    --  Type: Gint 
  357.    --  Flags: read-write 
  358.    --  The column of the model containing the strings. Note that the strings 
  359.    --  must be UTF-8. 
  360.  
  361.    Inline_Completion_Property : constant Glib.Properties.Property_Boolean; 
  362.    Inline_Selection_Property : constant Glib.Properties.Property_Boolean; 
  363.    Minimum_Key_Length_Property : constant Glib.Properties.Property_Int; 
  364.    Model_Property : constant Glib.Properties.Property_Object; 
  365.    Popup_Completion_Property : constant Glib.Properties.Property_Boolean; 
  366.    Popup_Set_Width_Property : constant Glib.Properties.Property_Boolean; 
  367.    Popup_Single_Match_Property : constant Glib.Properties.Property_Boolean; 
  368.    Text_Column_Property : constant Glib.Properties.Property_Int; 
  369.  
  370.    ------------- 
  371.    -- Signals -- 
  372.    ------------- 
  373.    --  The following new signals are defined for this widget: 
  374.    -- 
  375.    --  "action-activated" 
  376.    --     procedure Handler 
  377.    --       (Self  : access Gtk_Entry_Completion_Record'Class; 
  378.    --        Index : Gint); 
  379.    --    --  "index": the index of the activated action 
  380.    --  Gets emitted when an action is activated. 
  381.    -- 
  382.    --  "cursor-on-match" 
  383.    --     function Handler 
  384.    --       (Self  : access Gtk_Entry_Completion_Record'Class; 
  385.    --        Model : Gtk.Tree_Model.Gtk_Tree_Model; 
  386.    --        Iter  : TreeIter) return Boolean; 
  387.    --    --  "model": the Gtk.Tree_Model.Gtk_Tree_Model containing the matches 
  388.    --    --  "iter": a GtkTreeIter positioned at the selected match 
  389.    --  Gets emitted when a match from the cursor is on a match of the list.The 
  390.    --  default behaviour is to replace the contents of the entry with the 
  391.    --  contents of the text column in the row pointed to by Iter. 
  392.    --  Returns True if the signal has been handled 
  393.    -- 
  394.    --  "insert-prefix" 
  395.    --     function Handler 
  396.    --       (Self   : access Gtk_Entry_Completion_Record'Class; 
  397.    --        Prefix : UTF8_String) return Boolean; 
  398.    --    --  "prefix": the common prefix of all possible completions 
  399.    --  Gets emitted when the inline autocompletion is triggered. The default 
  400.    --  behaviour is to make the entry display the whole prefix and select the 
  401.    --  newly inserted part. Applications may connect to this signal in order to 
  402.    --  insert only a smaller part of the Prefix into the entry - e.g. the entry 
  403.    --  used in the Gtk.File_Chooser.Gtk_File_Chooser inserts only the part of 
  404.    --  the prefix up to the next '/'. 
  405.    --  Returns True if the signal has been handled 
  406.    -- 
  407.    --  "match-selected" 
  408.    --     function Handler 
  409.    --       (Self  : access Gtk_Entry_Completion_Record'Class; 
  410.    --        Model : Gtk.Tree_Model.Gtk_Tree_Model; 
  411.    --        Iter  : TreeIter) return Boolean; 
  412.    --    --  "model": the Gtk.Tree_Model.Gtk_Tree_Model containing the matches 
  413.    --    --  "iter": a GtkTreeIter positioned at the selected match 
  414.    --  Gets emitted when a match from the list is selected. The default 
  415.    --  behaviour is to replace the contents of the entry with the contents of 
  416.    --  the text column in the row pointed to by Iter. 
  417.    --  Returns True if the signal has been handled 
  418.  
  419.    Signal_Action_Activated : constant Glib.Signal_Name := "action-activated"; 
  420.    Signal_Cursor_On_Match : constant Glib.Signal_Name := "cursor-on-match"; 
  421.    Signal_Insert_Prefix : constant Glib.Signal_Name := "insert-prefix"; 
  422.    Signal_Match_Selected : constant Glib.Signal_Name := "match-selected"; 
  423.  
  424. private 
  425.    Inline_Completion_Property : constant Glib.Properties.Property_Boolean := 
  426.      Glib.Properties.Build ("inline-completion"); 
  427.    Inline_Selection_Property : constant Glib.Properties.Property_Boolean := 
  428.      Glib.Properties.Build ("inline-selection"); 
  429.    Minimum_Key_Length_Property : constant Glib.Properties.Property_Int := 
  430.      Glib.Properties.Build ("minimum-key-length"); 
  431.    Model_Property : constant Glib.Properties.Property_Object := 
  432.      Glib.Properties.Build ("model"); 
  433.    Popup_Completion_Property : constant Glib.Properties.Property_Boolean := 
  434.      Glib.Properties.Build ("popup-completion"); 
  435.    Popup_Set_Width_Property : constant Glib.Properties.Property_Boolean := 
  436.      Glib.Properties.Build ("popup-set-width"); 
  437.    Popup_Single_Match_Property : constant Glib.Properties.Property_Boolean := 
  438.      Glib.Properties.Build ("popup-single-match"); 
  439.    Text_Column_Property : constant Glib.Properties.Property_Int := 
  440.      Glib.Properties.Build ("text-column"); 
  441. end Gtk.Entry_Completion;