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-2007 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. -- -- -- -- -- -- -- -- -- -- -- --
  23. ----------------------------------------------------------------------- 
  24.  
  25. --  <description> 
  26. --  This widget provides completion functionality for Gtk.Gentry.Gtk_Entry. 
  27. -- 
  28. --  "Completion functionality" means that when the user modifies the text in 
  29. --  the entry, GtkEntryCompletion checks which rows in the model match the 
  30. --  current content of the entry, and displays a list of matches. By default, 
  31. --  the matching is done by comparing the entry text case-insensitively against 
  32. --  the text column of the model (see Set_Text_Column), but this can be 
  33. --  overridden with a custom match function (see Set_Match_Func). 
  34. -- 
  35. --  When the user selects a completion, the content of the entry is updated. By 
  36. --  default, the content of the entry is replaced by the text column of the 
  37. --  model, but this can be overridden by connecting to the ::match-selected 
  38. --  signal and updating the entry in the signal handler. Note that you should 
  39. --  return TRUE from the signal handler to suppress the default behaviour. 
  40. -- 
  41. --  To add completion functionality to an entry, use Gtk.Entry.Set_Completion. 
  42. -- 
  43. --  In addition to regular completion matches, which will be inserted into the 
  44. --  entry when they are selected, GtkEntryCompletion also allows to display 
  45. --  "actions" in the popup window. Their appearance is similar to menuitems, to 
  46. --  differentiate them clearly from completion strings. When an action is 
  47. --  selected, the ::action-activated signal is emitted. 
  48. --  </description> 
  49. --  <c_version>2.8.17</c_version> 
  50. --  <group>Numeric/Text Data Entry</group> 
  51.  
  52. with Glib.Object; 
  53. with Glib.Properties; 
  54. with Gtk.Tree_Model; 
  55. with Gtk.Widget; 
  56.  
  57. package Gtk.Entry_Completion is 
  58.    type Gtk_Entry_Completion_Record is new Glib.Object.GObject_Record 
  59.       with null record; 
  60.    type Gtk_Entry_Completion is access all Gtk_Entry_Completion_Record'Class; 
  61.  
  62.    procedure Gtk_New (Completion : out Gtk_Entry_Completion); 
  63.    procedure Initialize 
  64.      (Completion : access Gtk_Entry_Completion_Record'Class); 
  65.    --  Creates or initializes a new completion object 
  66.  
  67.    function Get_Type return Glib.GType; 
  68.    --  Return the internal type used for this object 
  69.  
  70.    procedure Complete 
  71.      (Completion : access Gtk_Entry_Completion_Record); 
  72.    --  Requests a completion operation, or in other words a refiltering of the 
  73.    --  current list with completions, using the current key. The completion 
  74.    --  list view will be updated accordingly. 
  75.  
  76.    procedure Delete_Action 
  77.      (Completion : access Gtk_Entry_Completion_Record; 
  78.       Index      : Gint); 
  79.    --  Deletes the action at index from completion's action list. 
  80.  
  81.    function Get_Entry 
  82.      (Completion : access Gtk_Entry_Completion_Record) 
  83.       return Gtk.Widget.Gtk_Widget; 
  84.    --  Gets the entry completion has been attached to. 
  85.  
  86.    procedure Set_Inline_Completion 
  87.      (Completion        : access Gtk_Entry_Completion_Record; 
  88.       Inline_Completion : Boolean); 
  89.    function Get_Inline_Completion 
  90.      (Completion : access Gtk_Entry_Completion_Record) 
  91.       return Boolean; 
  92.    --  Returns whether the common prefix of the possible completions should 
  93.    --  be automatically inserted in the entry. 
  94.    --  This text appears greyed out, and is removed when the user types some 
  95.    --  text not compatible with the possible completions 
  96.  
  97.    procedure Set_Minimum_Key_Length 
  98.      (Completion : access Gtk_Entry_Completion_Record; 
  99.       Length     : Gint); 
  100.    function Get_Minimum_Key_Length 
  101.      (Completion : access Gtk_Entry_Completion_Record) return Gint; 
  102.    --  Requires the length of the search key for completion to be at least 
  103.    --  length. This is useful for long lists, where completing using a small 
  104.    --  key takes a lot of time and will come up with meaningless results anyway 
  105.    --  (ie, a too large dataset). 
  106.    --  This is the minimal number of characters the user must start typing 
  107.    --  before any completion is attempted 
  108.  
  109.    procedure Set_Model 
  110.      (Completion : access Gtk_Entry_Completion_Record; 
  111.       Model      : Gtk.Tree_Model.Gtk_Tree_Model); 
  112.    function Get_Model 
  113.      (Completion : access Gtk_Entry_Completion_Record) 
  114.       return Gtk.Tree_Model.Gtk_Tree_Model; 
  115.    --  Returns the model the completion is using as data source. 
  116.    --  Returns null if the model is unset (setting it to null unsets the 
  117.    --  current model) 
  118.  
  119.    procedure Set_Popup_Completion 
  120.      (Completion       : access Gtk_Entry_Completion_Record; 
  121.       Popup_Completion : Boolean); 
  122.    function Get_Popup_Completion 
  123.      (Completion : access Gtk_Entry_Completion_Record) 
  124.       return Boolean; 
  125.    --  Returns whether the completions should be presented in a popup window. 
  126.    --  This is to be used in addition to, or instead of, Get_Inline_Completion. 
  127.  
  128.    procedure Set_Popup_Set_Width 
  129.      (Completion      : access Gtk_Entry_Completion_Record; 
  130.       Popup_Set_Width : Boolean); 
  131.    function Get_Popup_Set_Width 
  132.      (Completion : access Gtk_Entry_Completion_Record) 
  133.       return Boolean; 
  134.    --  Returns whether the  completion popup window will be resized to the 
  135.    --  width of the entry. 
  136.  
  137.    procedure Set_Popup_Single_Match 
  138.      (Completion         : access Gtk_Entry_Completion_Record; 
  139.       Popup_Single_Match : Boolean); 
  140.    function Get_Popup_Single_Match 
  141.      (Completion : access Gtk_Entry_Completion_Record) 
  142.       return Boolean; 
  143.    --  Returns whether the completion popup window will appear even if there is 
  144.    --  only a single match. 
  145.    --  You may want to set this to False if you are using inline completion. 
  146.  
  147.    procedure Set_Text_Column 
  148.      (Completion : access Gtk_Entry_Completion_Record; 
  149.       Column     : Gint); 
  150.    function Get_Text_Column 
  151.      (Completion : access Gtk_Entry_Completion_Record) return Gint; 
  152.    --  Convenience function for setting up the most used case of this code: a 
  153.    --  completion list with just strings. This function will set up completion 
  154.    --  to have a list displaying all (and just) strings in the completion list, 
  155.    --  and to get those strings from column in the model of completion. 
  156.    -- 
  157.    --  This functions creates and adds a #GtkCellRendererText for the selected 
  158.    --  column. If you need to set the text column, but don't want the cell 
  159.    --  renderer, use Set_Property to set the ::text_column property directly. 
  160.  
  161.    procedure Insert_Action_Markup 
  162.      (Completion : access Gtk_Entry_Completion_Record; 
  163.       Index      : Gint; 
  164.       Markup     : String); 
  165.    --  Inserts an action in ccompletion's action item list at position index 
  166.    --  with the given markup. Markup can be used to represent bold text, for 
  167.    --  instance with "<b>bold</b> text" 
  168.  
  169.    procedure Insert_Action_Text 
  170.      (Completion : access Gtk_Entry_Completion_Record; 
  171.       Index     : Gint; 
  172.       Text       : String); 
  173.    --  Inserts an action in completion's action item list at position index 
  174.    --  with text Text. If you want the action item to have markup, use 
  175.    --  Insert_Action_Markup. 
  176.  
  177.    procedure Insert_Prefix (Completion : access Gtk_Entry_Completion_Record); 
  178.    --  Requests a prefix insertion. 
  179.  
  180.    function Get_Completion_Prefix 
  181.      (Completion : access Gtk_Entry_Completion_Record) 
  182.       return String; 
  183.    --  Get the original text entered by the user that triggered 
  184.    --  the completion or "" if there's no completion ongoing. 
  185.  
  186.    function Get_Inline_Selection 
  187.      (Completion : access Gtk_Entry_Completion_Record) 
  188.       return Boolean; 
  189.    procedure Set_Inline_Selection 
  190.      (Completion       : access Gtk_Entry_Completion_Record; 
  191.       Inline_Selection : Boolean); 
  192.    --  Gets/Sets whether it is possible to cycle through the possible 
  193.    --  completions inside the entry. 
  194.  
  195.    generic 
  196.       type Data_Type (<>) is private; 
  197.    package Match_Functions is 
  198.       type Gtk_Entry_Completion_Match_Func is access 
  199.         function (Completion : access Gtk_Entry_Completion_Record'Class; 
  200.                   Key        : String; 
  201.                   Iter       : Gtk.Tree_Model.Gtk_Tree_Iter; 
  202.                   User_Data  : Data_Type) return Boolean; 
  203.  
  204.       type Destroy_Notify is access procedure (Data : in out Data_Type); 
  205.  
  206.       procedure Set_Match_Func 
  207.         (Completion  : access Gtk_Entry_Completion_Record; 
  208.          Func        : Gtk_Entry_Completion_Match_Func; 
  209.          Func_Data   : Data_Type; 
  210.          Func_Notify : Destroy_Notify); 
  211.       --  Sets the match function for completion to be Func. The match function 
  212.       --  is used to determine if a row should or should not be in the 
  213.       --  completion list. 
  214.    end Match_Functions; 
  215.  
  216.    ------------- 
  217.    -- Signals -- 
  218.    ------------- 
  219.  
  220.    --  <signals> 
  221.    --  The following new signals are defined for this widget: 
  222.    -- 
  223.    --  - "insert_prefix" 
  224.    --    procedure Handler 
  225.    --      (Completion : access Gtk_Entry_Completion_Record'Class; 
  226.    --       Prefix     : String); 
  227.    --    Gets emitted when the inline autocompletion is triggered. The default 
  228.    --    behaviour is to make the entry display the whole prefix and select the 
  229.    --    newly inserted part. 
  230.    --    Applications may connect to this signal in order to insert only 
  231.    --    smaller part of the Prefix into the entry - e.g. the entry used in 
  232.    --    the #GtkFileChooser inserts only the part of the prefix up to the next 
  233.    --    '/'. 
  234.    --    Return value: %TRUE if the signal has been handled 
  235.    -- 
  236.    --  - "action_activated" 
  237.    --    procedure Handler 
  238.    --       (Completion : access Gtk_Entry_Completion_Record'Class; 
  239.    --        Index      : Gint); 
  240.    --    Gets emitted when an action is activated. 
  241.    -- 
  242.    --  - "match_selected" 
  243.    --    procedure Handler 
  244.    --       (Completion : access Gtk_Entry_Completion_Record'Class; 
  245.    --        Model      : Gtk_Tree_Model; 
  246.    --        Iter       : Gtk_Tree_Iter); 
  247.    --    Gets emitted when a match from the list is selected. The default 
  248.    --    behaviour is to replace the contents of the entry with the contents of 
  249.    --    the text column in the row pointed to by Iter. 
  250.    --    Return value: %TRUE if the signal has been handled 
  251.    -- 
  252.    --  </signals> 
  253.  
  254.    Signal_Action_Activated : constant Glib.Signal_Name := "action_activated"; 
  255.    Signal_Insert_Prefix    : constant Glib.Signal_Name := "insert_prefix"; 
  256.    Signal_Match_Selected   : constant Glib.Signal_Name := "match_selected"; 
  257.  
  258.    ---------------- 
  259.    -- Properties -- 
  260.    ---------------- 
  261.  
  262.    --  <properties> 
  263.    --  The following properties are defined for this widget. See 
  264.    --  Glib.Properties for more information on properties. 
  265.    -- 
  266.    --  Name:  Inline_Completion_Property 
  267.    --  Type:  Boolean 
  268.    --  Descr: Whether the common prefix should be inserted automatically 
  269.    -- 
  270.    --  Name:  Inline_Selection_Property 
  271.    --  Type:  Boolean 
  272.    --  Descr: Whether you can cycle through possible completions inline 
  273.    -- 
  274.    --  Name:  Minimum_Key_Length_Property 
  275.    --  Type:  Int 
  276.    --  Descr: Minimum length of the search key in order to look up matches 
  277.    -- 
  278.    --  Name:  Model_Property 
  279.    --  Type:  Object 
  280.    --  Descr: The model to find matches in 
  281.    -- 
  282.    --  Name:  Popup_Completion_Property 
  283.    --  Type:  Boolean 
  284.    --  Descr: Whether the completions should be shown in a popup window 
  285.    -- 
  286.    --  Name:  Popup_Set_Width_Property 
  287.    --  Type:  Boolean 
  288.    --  Descr: If TRUE, the popup window will have the same size as the entry 
  289.    -- 
  290.    --  Name:  Popup_Single_Match_Property 
  291.    --  Type:  Boolean 
  292.    --  Descr: If TRUE, the popup window will appear for a single match. 
  293.    -- 
  294.    --  Name:  Text_Column_Property 
  295.    --  Type:  Int 
  296.    --  Descr: The column of the model containing the strings. 
  297.    -- 
  298.    --  </properties> 
  299.  
  300.    Inline_Completion_Property  : constant Glib.Properties.Property_Boolean; 
  301.    Inline_Selection_Property   : constant Glib.Properties.Property_Boolean; 
  302.    Minimum_Key_Length_Property : constant Glib.Properties.Property_Int; 
  303.    Model_Property              : constant Glib.Properties.Property_Object; 
  304.    Popup_Completion_Property   : constant Glib.Properties.Property_Boolean; 
  305.    Popup_Set_Width_Property    : constant Glib.Properties.Property_Boolean; 
  306.    Popup_Single_Match_Property : constant Glib.Properties.Property_Boolean; 
  307.    Text_Column_Property        : constant Glib.Properties.Property_Int; 
  308.  
  309. private 
  310.    Inline_Completion_Property : constant Glib.Properties.Property_Boolean := 
  311.      Glib.Properties.Build ("inline-completion"); 
  312.    Inline_Selection_Property : constant Glib.Properties.Property_Boolean := 
  313.      Glib.Properties.Build ("inline-selection"); 
  314.    Minimum_Key_Length_Property : constant Glib.Properties.Property_Int := 
  315.      Glib.Properties.Build ("minimum-key-length"); 
  316.    Model_Property : constant Glib.Properties.Property_Object := 
  317.      Glib.Properties.Build ("model"); 
  318.    Popup_Completion_Property : constant Glib.Properties.Property_Boolean := 
  319.      Glib.Properties.Build ("popup-completion"); 
  320.    Popup_Set_Width_Property : constant Glib.Properties.Property_Boolean := 
  321.      Glib.Properties.Build ("popup-set-width"); 
  322.    Popup_Single_Match_Property : constant Glib.Properties.Property_Boolean := 
  323.      Glib.Properties.Build ("popup-single-match"); 
  324.    Text_Column_Property : constant Glib.Properties.Property_Int := 
  325.      Glib.Properties.Build ("text-column"); 
  326.  
  327.    pragma Import (C, Get_Type, "gtk_entry_completion_get_type"); 
  328. end Gtk.Entry_Completion;