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