1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  Gtk.IM_Context.Gtk_IM_Context defines the interface for GTK+ input 
  26. --  methods. An input method is used by GTK+ text input widgets like 
  27. --  Gtk.GEntry.Gtk_Entry to map from key events to Unicode character strings. 
  28. -- 
  29. --  The user may change the current input method via a context menu, unless 
  30. --  the Gtk.Settings.Gtk_Settings:gtk-show-input-method-menu GtkSettings 
  31. --  property is set to FALSE. The default input method can be set 
  32. --  programmatically via the Gtk.Settings.Gtk_Settings:gtk-im-module 
  33. --  GtkSettings property. Alternatively, you may set the GTK_IM_MODULE 
  34. --  environment variable as documented in gtk-running. 
  35. -- 
  36. --  The Gtk.GEntry.Gtk_Entry Gtk.GEntry.Gtk_Entry:im-module and 
  37. --  Gtk.Text_View.Gtk_Text_View Gtk.Text_View.Gtk_Text_View:im-module 
  38. --  properties may also be used to set input methods for specific widget 
  39. --  instances. For instance, a certain entry widget might be expected to 
  40. --  contain certain characters which would be easier to input with a certain 
  41. --  input method. 
  42. -- 
  43. --  An input method may consume multiple key events in sequence and finally 
  44. --  output the composed result. This is called preediting, and an input method 
  45. --  may provide feedback about this process by displaying the intermediate 
  46. --  composition states as preedit text. For instance, the default GTK+ input 
  47. --  method implements the input of arbitrary Unicode code points by holding 
  48. --  down the Control and Shift keys and then typing "U" followed by the 
  49. --  hexadecimal digits of the code point. When releasing the Control and Shift 
  50. --  keys, preediting ends and the character is inserted as text. 
  51. --  Ctrl+Shift+u20AC for example results in the euro symbol. 
  52. -- 
  53. --  Additional input methods can be made available for use by GTK+ widgets as 
  54. --  loadable modules. An input method module is a small shared library which 
  55. --  implements a subclass of Gtk.IM_Context.Gtk_IM_Context or 
  56. --  Gtk.IM_Context_Simple.Gtk_IM_Context_Simple and exports these four 
  57. --  functions: 
  58. -- 
  59. --    void im_module_init(Gtype.Module.Gtype_Module *module); 
  60. -- 
  61. --  This function should register the GType of the 
  62. --  Gtk.IM_Context.Gtk_IM_Context subclass which implements the input method by 
  63. --  means of g_type_module_register_type. Note that g_type_register_static 
  64. --  cannot be used as the type needs to be registered dynamically. 
  65. -- 
  66. --    void im_module_exit(void); 
  67. -- 
  68. --  Here goes any cleanup code your input method might require on module 
  69. --  unload. 
  70. -- 
  71. --    void im_module_list(const Gtk_IMContext_Info ***contexts, int *n_contexts) 
  72. --    { 
  73. --       *contexts = info_list; 
  74. --       *n_contexts = G_N_ELEMENTS (info_list); 
  75. --    } 
  76. -- 
  77. --  This function returns the list of input methods provided by the module. 
  78. --  The example implementation above shows a common solution and simply returns 
  79. --  a pointer to statically defined array of Gtk_IMContext_Info items for each 
  80. --  provided input method. 
  81. -- 
  82. --    Gtk.IM_Context.Gtk_IM_Context * im_module_create(const Gchar *context_id); 
  83. -- 
  84. --  This function should return a pointer to a newly created instance of the 
  85. --  Gtk.IM_Context.Gtk_IM_Context subclass identified by Context_Id. The 
  86. --  context ID is the same as specified in the Gtk_IMContext_Info array 
  87. --  returned by im_module_list. 
  88. -- 
  89. --  After a new loadable input method module has been installed on the system, 
  90. --  the configuration file 'gtk.immodules' needs to be regenerated by <link 
  91. --  linkend="gtk-query-immodules-3.0">gtk-query-immodules-3.0</link>, in order 
  92. --  for the new input method to become available to GTK+ applications. 
  93. -- 
  94. --  </description> 
  95. pragma Ada_2005; 
  96.  
  97. pragma Warnings (Off, "*is already use-visible*"); 
  98. with Gdk;           use Gdk; 
  99. with Gdk.Event;     use Gdk.Event; 
  100. with Gdk.Rectangle; use Gdk.Rectangle; 
  101. with Glib;          use Glib; 
  102. with Glib.Object;   use Glib.Object; 
  103. with Gtk.Enums;     use Gtk.Enums; 
  104.  
  105. package Gtk.IM_Context is 
  106.  
  107.    type Gtk_IM_Context_Record is new GObject_Record with null record; 
  108.    type Gtk_IM_Context is access all Gtk_IM_Context_Record'Class; 
  109.  
  110.    ------------------ 
  111.    -- Constructors -- 
  112.    ------------------ 
  113.  
  114.    function Get_Type return Glib.GType; 
  115.    pragma Import (C, Get_Type, "gtk_im_context_get_type"); 
  116.  
  117.    ------------- 
  118.    -- Methods -- 
  119.    ------------- 
  120.  
  121.    function Delete_Surrounding 
  122.       (Self    : not null access Gtk_IM_Context_Record; 
  123.        Offset  : Gint; 
  124.        N_Chars : Gint) return Boolean; 
  125.    --  Asks the widget that the input context is attached to to delete 
  126.    --  characters around the cursor position by emitting the 
  127.    --  GtkIMContext::delete_surrounding signal. Note that Offset and N_Chars 
  128.    --  are in characters not in bytes which differs from the usage other places 
  129.    --  in Gtk.IM_Context.Gtk_IM_Context. 
  130.    --  In order to use this function, you should first call 
  131.    --  gtk_im_context_get_surrounding to get the current context, and call this 
  132.    --  function immediately afterwards to make sure that you know what you are 
  133.    --  deleting. You should also account for the fact that even if the signal 
  134.    --  was handled, the input context might not have deleted all the characters 
  135.    --  that were requested to be deleted. 
  136.    --  This function is used by an input method that wants to make 
  137.    --  subsitutions in the existing text in response to new input. It is not 
  138.    --  useful for applications. 
  139.    --  "offset": offset from cursor position in chars; a negative value means 
  140.    --  start before the cursor. 
  141.    --  "n_chars": number of characters to delete. 
  142.  
  143.    function Filter_Keypress 
  144.       (Self  : not null access Gtk_IM_Context_Record; 
  145.        Event : Gdk.Event.Gdk_Event_Key) return Boolean; 
  146.    --  Allow an input method to internally handle key press and release 
  147.    --  events. If this function returns True, then no further processing should 
  148.    --  be done for this key event. 
  149.    --  "event": the key event 
  150.  
  151.    procedure Focus_In (Self : not null access Gtk_IM_Context_Record); 
  152.    --  Notify the input method that the widget to which this input context 
  153.    --  corresponds has gained focus. The input method may, for example, change 
  154.    --  the displayed feedback to reflect this change. 
  155.  
  156.    procedure Focus_Out (Self : not null access Gtk_IM_Context_Record); 
  157.    --  Notify the input method that the widget to which this input context 
  158.    --  corresponds has lost focus. The input method may, for example, change 
  159.    --  the displayed feedback or reset the contexts state to reflect this 
  160.    --  change. 
  161.  
  162.    procedure Reset (Self : not null access Gtk_IM_Context_Record); 
  163.    --  Notify the input method that a change such as a change in cursor 
  164.    --  position has been made. This will typically cause the input method to 
  165.    --  clear the preedit state. 
  166.  
  167.    procedure Set_Client_Window 
  168.       (Self   : not null access Gtk_IM_Context_Record; 
  169.        Window : Gdk.Gdk_Window); 
  170.    --  Set the client window for the input context; this is the Gdk.Gdk_Window 
  171.    --  in which the input appears. This window is used in order to correctly 
  172.    --  position status windows, and may also be used for purposes internal to 
  173.    --  the input method. 
  174.    --  "window": the client window. This may be null to indicate that the 
  175.    --  previous client window no longer exists. 
  176.  
  177.    procedure Set_Cursor_Location 
  178.       (Self : not null access Gtk_IM_Context_Record; 
  179.        Area : Gdk.Rectangle.Gdk_Rectangle); 
  180.    --  Notify the input method that a change in cursor position has been made. 
  181.    --  The location is relative to the client window. 
  182.    --  "area": new location 
  183.  
  184.    procedure Set_Surrounding 
  185.       (Self         : not null access Gtk_IM_Context_Record; 
  186.        Text         : UTF8_String; 
  187.        Len          : Gint; 
  188.        Cursor_Index : Gint); 
  189.    --  Sets surrounding context around the insertion point and preedit string. 
  190.    --  This function is expected to be called in response to the 
  191.    --  GtkIMContext::retrieve_surrounding signal, and will likely have no 
  192.    --  effect if called at other times. 
  193.    --  "text": text surrounding the insertion point, as UTF-8. the preedit 
  194.    --  string should not be included within Text. 
  195.    --  "len": the length of Text, or -1 if Text is nul-terminated 
  196.    --  "cursor_index": the byte index of the insertion cursor within Text. 
  197.  
  198.    procedure Set_Use_Preedit 
  199.       (Self        : not null access Gtk_IM_Context_Record; 
  200.        Use_Preedit : Boolean); 
  201.    --  Sets whether the IM context should use the preedit string to display 
  202.    --  feedback. If Use_Preedit is FALSE (default is TRUE), then the IM context 
  203.    --  may use some other method to display feedback, such as displaying it in 
  204.    --  a child of the root window. 
  205.    --  "use_preedit": whether the IM context should use the preedit string. 
  206.  
  207.    ---------------- 
  208.    -- Properties -- 
  209.    ---------------- 
  210.    --  The following properties are defined for this widget. See 
  211.    --  Glib.Properties for more information on properties) 
  212.  
  213.    Input_Hints_Property : constant Gtk.Enums.Property_Gtk_Input_Hints; 
  214.  
  215.    Input_Purpose_Property : constant Gtk.Enums.Property_Gtk_Input_Purpose; 
  216.  
  217.    ------------- 
  218.    -- Signals -- 
  219.    ------------- 
  220.  
  221.    type Cb_Gtk_IM_Context_UTF8_String_Void is not null access procedure 
  222.      (Self : access Gtk_IM_Context_Record'Class; 
  223.       Str  : UTF8_String); 
  224.  
  225.    type Cb_GObject_UTF8_String_Void is not null access procedure 
  226.      (Self : access Glib.Object.GObject_Record'Class; 
  227.       Str  : UTF8_String); 
  228.  
  229.    Signal_Commit : constant Glib.Signal_Name := "commit"; 
  230.    procedure On_Commit 
  231.       (Self  : not null access Gtk_IM_Context_Record; 
  232.        Call  : Cb_Gtk_IM_Context_UTF8_String_Void; 
  233.        After : Boolean := False); 
  234.    procedure On_Commit 
  235.       (Self  : not null access Gtk_IM_Context_Record; 
  236.        Call  : Cb_GObject_UTF8_String_Void; 
  237.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  238.        After : Boolean := False); 
  239.    --  The ::commit signal is emitted when a complete input sequence has been 
  240.    --  entered by the user. This can be a single character immediately after a 
  241.    --  key press or the final result of preediting. 
  242.  
  243.    type Cb_Gtk_IM_Context_Gint_Gint_Boolean is not null access function 
  244.      (Self    : access Gtk_IM_Context_Record'Class; 
  245.       Offset  : Gint; 
  246.       N_Chars : Gint) return Boolean; 
  247.  
  248.    type Cb_GObject_Gint_Gint_Boolean is not null access function 
  249.      (Self    : access Glib.Object.GObject_Record'Class; 
  250.       Offset  : Gint; 
  251.       N_Chars : Gint) return Boolean; 
  252.  
  253.    Signal_Delete_Surrounding : constant Glib.Signal_Name := "delete-surrounding"; 
  254.    procedure On_Delete_Surrounding 
  255.       (Self  : not null access Gtk_IM_Context_Record; 
  256.        Call  : Cb_Gtk_IM_Context_Gint_Gint_Boolean; 
  257.        After : Boolean := False); 
  258.    procedure On_Delete_Surrounding 
  259.       (Self  : not null access Gtk_IM_Context_Record; 
  260.        Call  : Cb_GObject_Gint_Gint_Boolean; 
  261.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  262.        After : Boolean := False); 
  263.    --  The ::delete-surrounding signal is emitted when the input method needs 
  264.    --  to delete all or part of the context surrounding the cursor. 
  265.    --  
  266.    --  Callback parameters: 
  267.    --    --  "offset": the character offset from the cursor position of the text to 
  268.    --    --  be deleted. A negative value indicates a position before the cursor. 
  269.    --    --  "n_chars": the number of characters to be deleted 
  270.    --    --  Returns True if the signal was handled. 
  271.  
  272.    type Cb_Gtk_IM_Context_Void is not null access procedure (Self : access Gtk_IM_Context_Record'Class); 
  273.  
  274.    type Cb_GObject_Void is not null access procedure 
  275.      (Self : access Glib.Object.GObject_Record'Class); 
  276.  
  277.    Signal_Preedit_Changed : constant Glib.Signal_Name := "preedit-changed"; 
  278.    procedure On_Preedit_Changed 
  279.       (Self  : not null access Gtk_IM_Context_Record; 
  280.        Call  : Cb_Gtk_IM_Context_Void; 
  281.        After : Boolean := False); 
  282.    procedure On_Preedit_Changed 
  283.       (Self  : not null access Gtk_IM_Context_Record; 
  284.        Call  : Cb_GObject_Void; 
  285.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  286.        After : Boolean := False); 
  287.    --  The ::preedit-changed signal is emitted whenever the preedit sequence 
  288.    --  currently being entered has changed. It is also emitted at the end of a 
  289.    --  preedit sequence, in which case gtk_im_context_get_preedit_string 
  290.    --  returns the empty string. 
  291.  
  292.    Signal_Preedit_End : constant Glib.Signal_Name := "preedit-end"; 
  293.    procedure On_Preedit_End 
  294.       (Self  : not null access Gtk_IM_Context_Record; 
  295.        Call  : Cb_Gtk_IM_Context_Void; 
  296.        After : Boolean := False); 
  297.    procedure On_Preedit_End 
  298.       (Self  : not null access Gtk_IM_Context_Record; 
  299.        Call  : Cb_GObject_Void; 
  300.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  301.        After : Boolean := False); 
  302.    --  The ::preedit-end signal is emitted when a preediting sequence has been 
  303.    --  completed or canceled. 
  304.  
  305.    Signal_Preedit_Start : constant Glib.Signal_Name := "preedit-start"; 
  306.    procedure On_Preedit_Start 
  307.       (Self  : not null access Gtk_IM_Context_Record; 
  308.        Call  : Cb_Gtk_IM_Context_Void; 
  309.        After : Boolean := False); 
  310.    procedure On_Preedit_Start 
  311.       (Self  : not null access Gtk_IM_Context_Record; 
  312.        Call  : Cb_GObject_Void; 
  313.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  314.        After : Boolean := False); 
  315.    --  The ::preedit-start signal is emitted when a new preediting sequence 
  316.    --  starts. 
  317.  
  318.    type Cb_Gtk_IM_Context_Boolean is not null access function 
  319.      (Self : access Gtk_IM_Context_Record'Class) return Boolean; 
  320.  
  321.    type Cb_GObject_Boolean is not null access function 
  322.      (Self : access Glib.Object.GObject_Record'Class) 
  323.    return Boolean; 
  324.  
  325.    Signal_Retrieve_Surrounding : constant Glib.Signal_Name := "retrieve-surrounding"; 
  326.    procedure On_Retrieve_Surrounding 
  327.       (Self  : not null access Gtk_IM_Context_Record; 
  328.        Call  : Cb_Gtk_IM_Context_Boolean; 
  329.        After : Boolean := False); 
  330.    procedure On_Retrieve_Surrounding 
  331.       (Self  : not null access Gtk_IM_Context_Record; 
  332.        Call  : Cb_GObject_Boolean; 
  333.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  334.        After : Boolean := False); 
  335.    --  The ::retrieve-surrounding signal is emitted when the input method 
  336.    --  requires the context surrounding the cursor. The callback should set the 
  337.    --  input method surrounding context by calling the 
  338.    --  Gtk.IM_Context.Set_Surrounding method. 
  339.    --  
  340.    --  Callback parameters: 
  341.    --    --  Returns True if the signal was handled. 
  342.  
  343. private 
  344.    Input_Purpose_Property : constant Gtk.Enums.Property_Gtk_Input_Purpose := 
  345.      Gtk.Enums.Build ("input-purpose"); 
  346.    Input_Hints_Property : constant Gtk.Enums.Property_Gtk_Input_Hints := 
  347.      Gtk.Enums.Build ("input-hints"); 
  348. end Gtk.IM_Context;