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