------------------------------------------------------------------------------ -- -- -- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet -- -- Copyright (C) 2000-2014, AdaCore -- -- -- -- This library is free software; you can redistribute it and/or modify it -- -- under terms of the GNU General Public License as published by the Free -- -- Software Foundation; either version 3, or (at your option) any later -- -- version. This library is distributed in the hope that it will be useful, -- -- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- -- -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. -- -- -- -- As a special exception under Section 7 of GPL version 3, you are granted -- -- additional permissions described in the GCC Runtime Library Exception, -- -- version 3.1, as published by the Free Software Foundation. -- -- -- -- You should have received a copy of the GNU General Public License and -- -- a copy of the GCC Runtime Library Exception along with this program; -- -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- -- <http://www.gnu.org/licenses/>. -- -- -- ------------------------------------------------------------------------------ -- <description> -- Gtk.IM_Context.Gtk_IM_Context defines the interface for GTK+ input -- methods. An input method is used by GTK+ text input widgets like -- Gtk.GEntry.Gtk_Entry to map from key events to Unicode character strings. -- -- The user may change the current input method via a context menu, unless -- the Gtk.Settings.Gtk_Settings:gtk-show-input-method-menu GtkSettings -- property is set to FALSE. The default input method can be set -- programmatically via the Gtk.Settings.Gtk_Settings:gtk-im-module -- GtkSettings property. Alternatively, you may set the GTK_IM_MODULE -- environment variable as documented in gtk-running. -- -- The Gtk.GEntry.Gtk_Entry Gtk.GEntry.Gtk_Entry:im-module and -- Gtk.Text_View.Gtk_Text_View Gtk.Text_View.Gtk_Text_View:im-module -- properties may also be used to set input methods for specific widget -- instances. For instance, a certain entry widget might be expected to -- contain certain characters which would be easier to input with a certain -- input method. -- -- An input method may consume multiple key events in sequence and finally -- output the composed result. This is called preediting, and an input method -- may provide feedback about this process by displaying the intermediate -- composition states as preedit text. For instance, the default GTK+ input -- method implements the input of arbitrary Unicode code points by holding -- down the Control and Shift keys and then typing "U" followed by the -- hexadecimal digits of the code point. When releasing the Control and Shift -- keys, preediting ends and the character is inserted as text. -- Ctrl+Shift+u20AC for example results in the euro symbol. -- -- Additional input methods can be made available for use by GTK+ widgets as -- loadable modules. An input method module is a small shared library which -- implements a subclass of Gtk.IM_Context.Gtk_IM_Context or -- Gtk.IM_Context_Simple.Gtk_IM_Context_Simple and exports these four -- functions: -- -- void im_module_init(Gtype.Module.Gtype_Module *module); -- -- This function should register the GType of the -- Gtk.IM_Context.Gtk_IM_Context subclass which implements the input method by -- means of g_type_module_register_type. Note that g_type_register_static -- cannot be used as the type needs to be registered dynamically. -- -- void im_module_exit(void); -- -- Here goes any cleanup code your input method might require on module -- unload. -- -- void im_module_list(const Gtk_IMContext_Info ***contexts, int *n_contexts) -- { -- *contexts = info_list; -- *n_contexts = G_N_ELEMENTS (info_list); -- } -- -- This function returns the list of input methods provided by the module. -- The example implementation above shows a common solution and simply returns -- a pointer to statically defined array of Gtk_IMContext_Info items for each -- provided input method. -- -- Gtk.IM_Context.Gtk_IM_Context * im_module_create(const Gchar *context_id); -- -- This function should return a pointer to a newly created instance of the -- Gtk.IM_Context.Gtk_IM_Context subclass identified by Context_Id. The -- context ID is the same as specified in the Gtk_IMContext_Info array -- returned by im_module_list. -- -- After a new loadable input method module has been installed on the system, -- the configuration file 'gtk.immodules' needs to be regenerated by <link -- linkend="gtk-query-immodules-3.0">gtk-query-immodules-3.0</link>, in order -- for the new input method to become available to GTK+ applications. -- -- </description> pragma Ada_2005; pragma Warnings (Off, "*is already use-visible*");
with Gdk; use Gdk;
with Gdk.Event; use Gdk.Event;
with Gdk.Rectangle; use Gdk.Rectangle;
with Glib; use Glib;
with Glib.Object; use Glib.Object;
with Gtk.Enums; use Gtk.Enums;
package Gtk.IM_Context is
type Gtk_IM_Context_Record is new GObject_Record with null record;
type Gtk_IM_Context is access all Gtk_IM_Context_Record'Class;
------------------ -- Constructors -- ------------------ function Get_Type return Glib.GType;
pragma Import (C, Get_Type, "gtk_im_context_get_type");
------------- -- Methods -- ------------- function Delete_Surrounding
(Self : not null access Gtk_IM_Context_Record;
Offset : Gint;
N_Chars : Gint) return Boolean;
-- Asks the widget that the input context is attached to to delete -- characters around the cursor position by emitting the -- GtkIMContext::delete_surrounding signal. Note that Offset and N_Chars -- are in characters not in bytes which differs from the usage other places -- in Gtk.IM_Context.Gtk_IM_Context. -- In order to use this function, you should first call -- gtk_im_context_get_surrounding to get the current context, and call this -- function immediately afterwards to make sure that you know what you are -- deleting. You should also account for the fact that even if the signal -- was handled, the input context might not have deleted all the characters -- that were requested to be deleted. -- This function is used by an input method that wants to make -- subsitutions in the existing text in response to new input. It is not -- useful for applications. -- "offset": offset from cursor position in chars; a negative value means -- start before the cursor. -- "n_chars": number of characters to delete. function Filter_Keypress
(Self : not null access Gtk_IM_Context_Record;
Event : Gdk.Event.Gdk_Event_Key) return Boolean;
-- Allow an input method to internally handle key press and release -- events. If this function returns True, then no further processing should -- be done for this key event. -- "event": the key event procedure Focus_In (Self : not null access Gtk_IM_Context_Record);
-- Notify the input method that the widget to which this input context -- corresponds has gained focus. The input method may, for example, change -- the displayed feedback to reflect this change. procedure Focus_Out (Self : not null access Gtk_IM_Context_Record);
-- Notify the input method that the widget to which this input context -- corresponds has lost focus. The input method may, for example, change -- the displayed feedback or reset the contexts state to reflect this -- change. procedure Reset (Self : not null access Gtk_IM_Context_Record);
-- Notify the input method that a change such as a change in cursor -- position has been made. This will typically cause the input method to -- clear the preedit state. procedure Set_Client_Window
(Self : not null access Gtk_IM_Context_Record;
Window : Gdk.Gdk_Window);
-- Set the client window for the input context; this is the Gdk.Gdk_Window -- in which the input appears. This window is used in order to correctly -- position status windows, and may also be used for purposes internal to -- the input method. -- "window": the client window. This may be null to indicate that the -- previous client window no longer exists. procedure Set_Cursor_Location
(Self : not null access Gtk_IM_Context_Record;
Area : Gdk.Rectangle.Gdk_Rectangle);
-- Notify the input method that a change in cursor position has been made. -- The location is relative to the client window. -- "area": new location procedure Set_Surrounding
(Self : not null access Gtk_IM_Context_Record;
Text : UTF8_String;
Len : Gint;
Cursor_Index : Gint);
-- Sets surrounding context around the insertion point and preedit string. -- This function is expected to be called in response to the -- GtkIMContext::retrieve_surrounding signal, and will likely have no -- effect if called at other times. -- "text": text surrounding the insertion point, as UTF-8. the preedit -- string should not be included within Text. -- "len": the length of Text, or -1 if Text is nul-terminated -- "cursor_index": the byte index of the insertion cursor within Text. procedure Set_Use_Preedit
(Self : not null access Gtk_IM_Context_Record;
Use_Preedit : Boolean);
-- Sets whether the IM context should use the preedit string to display -- feedback. If Use_Preedit is FALSE (default is TRUE), then the IM context -- may use some other method to display feedback, such as displaying it in -- a child of the root window. -- "use_preedit": whether the IM context should use the preedit string. ---------------- -- Properties -- ---------------- -- The following properties are defined for this widget. See -- Glib.Properties for more information on properties) Input_Hints_Property : constant Gtk.Enums.Property_Gtk_Input_Hints;
Input_Purpose_Property : constant Gtk.Enums.Property_Gtk_Input_Purpose;
------------- -- Signals -- ------------- type Cb_Gtk_IM_Context_UTF8_String_Void is not null access procedure
(Self : access Gtk_IM_Context_Record'Class;
Str : UTF8_String); type Cb_GObject_UTF8_String_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class;
Str : UTF8_String); Signal_Commit : constant Glib.Signal_Name := "commit";
procedure On_Commit
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_Gtk_IM_Context_UTF8_String_Void;
After : Boolean := False);
procedure On_Commit
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_GObject_UTF8_String_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- The ::commit signal is emitted when a complete input sequence has been -- entered by the user. This can be a single character immediately after a -- key press or the final result of preediting. type Cb_Gtk_IM_Context_Gint_Gint_Boolean is not null access function
(Self : access Gtk_IM_Context_Record'Class;
Offset : Gint; N_Chars : Gint) return Boolean;
type Cb_GObject_Gint_Gint_Boolean is not null access function
(Self : access Glib.Object.GObject_Record'Class;
Offset : Gint; N_Chars : Gint) return Boolean;
Signal_Delete_Surrounding : constant Glib.Signal_Name := "delete-surrounding";
procedure On_Delete_Surrounding
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_Gtk_IM_Context_Gint_Gint_Boolean;
After : Boolean := False);
procedure On_Delete_Surrounding
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_GObject_Gint_Gint_Boolean;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- The ::delete-surrounding signal is emitted when the input method needs -- to delete all or part of the context surrounding the cursor. -- -- Callback parameters: -- -- "offset": the character offset from the cursor position of the text to -- -- be deleted. A negative value indicates a position before the cursor. -- -- "n_chars": the number of characters to be deleted -- -- Returns True if the signal was handled. type Cb_Gtk_IM_Context_Void is not null access procedure (Self : access Gtk_IM_Context_Record'Class);
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
Signal_Preedit_Changed : constant Glib.Signal_Name := "preedit-changed";
procedure On_Preedit_Changed
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_Gtk_IM_Context_Void;
After : Boolean := False);
procedure On_Preedit_Changed
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- The ::preedit-changed signal is emitted whenever the preedit sequence -- currently being entered has changed. It is also emitted at the end of a -- preedit sequence, in which case gtk_im_context_get_preedit_string -- returns the empty string. Signal_Preedit_End : constant Glib.Signal_Name := "preedit-end";
procedure On_Preedit_End
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_Gtk_IM_Context_Void;
After : Boolean := False);
procedure On_Preedit_End
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- The ::preedit-end signal is emitted when a preediting sequence has been -- completed or canceled. Signal_Preedit_Start : constant Glib.Signal_Name := "preedit-start";
procedure On_Preedit_Start
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_Gtk_IM_Context_Void;
After : Boolean := False);
procedure On_Preedit_Start
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- The ::preedit-start signal is emitted when a new preediting sequence -- starts. type Cb_Gtk_IM_Context_Boolean is not null access function
(Self : access Gtk_IM_Context_Record'Class) return Boolean;
type Cb_GObject_Boolean is not null access function
(Self : access Glib.Object.GObject_Record'Class)
return Boolean; Signal_Retrieve_Surrounding : constant Glib.Signal_Name := "retrieve-surrounding";
procedure On_Retrieve_Surrounding
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_Gtk_IM_Context_Boolean;
After : Boolean := False);
procedure On_Retrieve_Surrounding
(Self : not null access Gtk_IM_Context_Record;
Call : Cb_GObject_Boolean;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- The ::retrieve-surrounding signal is emitted when the input method -- requires the context surrounding the cursor. The callback should set the -- input method surrounding context by calling the -- Gtk.IM_Context.Set_Surrounding method. -- -- Callback parameters: -- -- Returns True if the signal was handled. private Input_Purpose_Property : constant Gtk.Enums.Property_Gtk_Input_Purpose :=
Gtk.Enums.Build ("input-purpose");
Input_Hints_Property : constant Gtk.Enums.Property_Gtk_Input_Hints :=
Gtk.Enums.Build ("input-hints");
end Gtk.IM_Context;