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