/src/wrappers/gtk/library/gtk_editable.e

  1indexing
  2	description: "GtkEditable -- Interface for text-editing widgets."
  3	copyright: "[
  4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20				]"
 21	date: "$Date:$"
 22	revision: "$Revision:$"
 23
 24			-- The GtkEditable interface is an interface which should be
 25			-- implemented by text editing widgets, such as GtkEntry and
 26			-- GtkText. It contains functions for generically
 27			-- manipulating an editable widget, a large number of action
 28			-- signals used for key bindings, and several signals that an
 29			-- application can connect to to modify the behavior of a
 30			-- widget.
 31
 32			-- As an example of the latter usage, by connecting the
 33			-- following handler to "insert_text", an application can
 34			-- convert all entry into a widget into uppercase.
 35
 36			-- Example 3. Forcing entry to uppercase.
 37	
 38			-- include <ctype.h>
 39	
 40			-- void
 41			-- insert_text_handler (GtkEditable *editable,
 42			--                      const gchar *text,
 43			--                      gint         length,
 44			--                      gint        *position,
 45			--                      gpointer     data)
 46			-- {
 47			--   int i;
 48			--   gchar *result = g_utf8_strup (text, length);
 49	
 50			--   g_signal_handlers_block_by_func (editable,
 51			-- 				   (gpointer) insert_text_handler, data);
 52			--   gtk_editable_insert_text (editable, result, length, position);
 53			--   g_signal_handlers_unblock_by_func (editable,
 54			--                                      (gpointer) insert_text_handler, data);
 55			--   g_signal_stop_emission_by_name (editable, "insert_text"); 
 56			--   g_free (result);
 57			-- }
 58
 59deferred class GTK_EDITABLE
 60inherit
 61	GTK_WIDGET
 62		-- DELETE: undefine make end
 63		-- TODO check this, since I'm not sure. Indeed any known
 64		-- implementation is a GTK_WIDGET, therefore it shouldn't bring
 65		-- any harm.
 66insert
 67	GTK_EDITABLE_EXTERNALS
 68	GTK_EDITABLE_STRUCT
 69		-- Known Implementations: GtkEditable is implemented by
 70		-- GtkEntry, GtkOldEditable, GtkSpinButton and GtkText.
 71
 72feature
 73	select_region (a_start, an_end: INTEGER) is
 74			-- Selects a region of text. The characters that are selected
 75			-- are those characters at positions from `a_start' up to,
 76			-- but not including `an_end'. If `an_end' is negative, then
 77			-- the the characters selected will be those characters from
 78			-- `a_start' to the end of the text.
 79		do
 80			gtk_editable_select_region (handle, a_start, an_end)
 81		end
 82
 83	selection_bounds: TUPLE[BOOLEAN,INTEGER,INTEGER] is
 84			-- current selection bounds, and if there is a selection. The
 85			-- format of the tuple is [`is_there_a_selection',
 86			-- `start',`end'].
 87		local is_there,a_start,an_end: INTEGER
 88		do
 89			is_there := gtk_editable_get_selection_bounds(handle,$a_start,$an_end)
 90			create Result.make_3 (is_there.to_boolean,a_start,an_end)
 91		end
 92
 93	insert_text (a_text: STRING; a_position: REFERENCE [INTEGER]) is
 94			-- Inserts `a_text' at `a_position'.
 95		local io_position: INTEGER
 96		do
 97			-- editable : 	a GtkEditable widget.
 98			
 99			-- new_text : 	the text to insert.
100			
101			-- new_text_length : 	the length of the text to insert, in bytes
102			
103			-- position : an inout parameter. The caller initializes it
104			-- to the position at which to insert the text. After the
105			-- call it points at the position after the newly inserted
106			-- text.
107			
108--			not_yet_implemented -- TODO missing position_ptr := WHAT? + a_position
109			io_position := a_position.item
110			gtk_editable_insert_text (handle, a_text.to_external, a_text.count, $io_position)
111			a_position.set_item (io_position)
112		end
113
114	delete_text (a_start, an_end: INTEGER) is
115			-- Deletes a sequence of characters. The characters that are
116			-- deleted are those characters at positions from `a_start'
117			-- up to, but not including `an_end'. If `an_end' is
118			-- negative, then the the characters deleted will be those
119			-- characters from 'a_start' to the end of the text.
120		do
121			gtk_editable_delete_text (handle,a_start, an_end)
122		end
123
124	substring (a_start, an_end: INTEGER): STRING is
125			-- Retrieves a sequence of characters. The characters that
126			-- are retrieved are those characters at positions from
127			-- `a_start' up to, but not including `an_end'. If `an_end'
128			-- is negative, then the the characters retrieved will be
129			-- those characters from `a_start' to the end of the text.
130		do
131			create Result.from_external(gtk_editable_get_chars (handle,a_start,an_end))
132			-- Using from_external, since the return value of
133			-- gtk_editable_get_chars are the characters in the indicated
134			-- region. The result must be freed with g_free() when the
135			-- application is finished with it.
136		end
137
138	cut_clipboard is
139			-- Causes the characters in the current selection to be
140			-- copied to the clipboard and then deleted from the widget.
141		do
142			gtk_editable_cut_clipboard (handle)
143		end
144
145	copy_clipboard is
146			-- Causes the characters in the current selection to be
147			-- copied to the clipboard.
148		do
149			gtk_editable_copy_clipboard (handle)
150		end
151
152	paste_clipboard is
153			-- Causes the contents of the clipboard to be pasted into the
154			-- given widget at the current cursor position.
155		do
156			gtk_editable_paste_clipboard (handle)
157		end
158
159	delete_selection is
160			-- Deletes the current contents of the widgets selection and disclaims the selection.
161		do
162			gtk_editable_delete_selection (handle)
163		end
164
165	set_position (a_position: INTEGER) is
166			-- Sets the cursor position. The cursor is displayed before
167			-- the character with the given (base 0) index in the
168			-- widget. The value must be less than or equal to the number
169			-- of characters in the widget. A value of -1 indicates that
170			-- the position should be set after the last character in the
171			-- entry. Note that this position is in characters, not in
172			-- bytes.
173		do
174			gtk_editable_set_position (handle,a_position)
175		end
176
177	position: INTEGER is
178			-- current cursor position. The cursor is displayed before
179			-- the character with the given (base 0) index in the
180			-- widget. The value will be less than or equal to the number
181			-- of characters in the widget. Note that this position is in
182			-- characters, not in bytes.
183		do
184			Result:=gtk_editable_get_position (handle)
185		end
186
187	set_editable is
188			-- Allow the user to edit the text
189		do
190			gtk_editable_set_editable (handle,1)
191		ensure is_editable
192		end
193
194	unset_editable is
195			-- Forbid the user to edit the text
196		do
197			gtk_editable_set_editable (handle,0)
198		ensure not is_editable
199		end
200
201	is_editable: BOOLEAN is
202			-- is the text editable by the user?
203		do
204			Result := (gtk_editable_get_editable(handle)).to_boolean
205		end
206
207feature -- The "changed" signal
208	changed_signal_name: STRING is "changed"
209	enable_on_changed is
210			-- Connects "changed" signal to `on_changed' feature.
211		do
212			connect (Current, changed_signal_name, $on_changed)
213		end
214
215	on_changed is
216			-- Built-in changed signal handler; empty by design; redefine it.
217
218			-- Indicates that the user has changed the contents of the widget.
219		do
220		end
221
222	connect_agent_to_changed_signal (a_procedure: PROCEDURE [ANY, TUPLE[GTK_EDITABLE]]) is
223		require valid_procedure: a_procedure /= Void
224		local changed_callback: CHANGED_CALLBACK [like Current]
225		do
226			create changed_callback.make
227			changed_callback.connect (Current, a_procedure)
228		end
229	
230	-- Signal Details
231	-- The "changed" signal
232	
233	-- void user_function (GtkEditable *editable, gpointer user_data);
234
235	
236	-- editable : 	the object which received the signal.
237	-- user_data : 	user data set when the signal handler was connected.
238
239feature -- The "delete-text" signal
240
241	-- void user_function (GtkEditable *editable, gint `a_start', gint
242	-- `an_end', gpointer user_data);
243
244	-- This signal is emitted when text is deleted from the widget by
245	-- the user. The default handler for this signal will normally be
246	-- responsible for inserting the text, so by connecting to this
247	-- signal and then stopping the signal with gtk_signal_emit_stop(),
248	-- it is possible to modify the inserted text, or prevent it from
249	-- being inserted entirely. The `a_start' and `an_end' parameters
250	-- are interpreted as for gtk_editable_delete_text()
251	
252	-- editable : 	the object which received the signal.
253	-- `a_start' : 	the starting position.
254	-- `an_end' : 	the end position.
255	-- user_data : 	user data set when the signal handler was connected.
256	
257
258feature -- The "insert-text" signal
259
260	insert_text_signal_name: STRING is "insert-text"
261		-- 		"insert-text"
262		--             void        user_function      (GtkEditable *editable,
263		--                                             gchar       *new_text,
264		--                                             gint         new_text_length,
265		--                                             gint        *position,
266		--                                             gpointer     user_data)            : Run last
267
268	on_insert_text is
269			-- Built-in insert-text signal handler; empty by design; redefine it.
270		do
271		end
272
273	enable_on_insert_text is
274			-- Connects "insert-text" signal to `on_insert_text' feature.
275			
276			-- This signal is emitted when text is inserted into the widget by
277			-- the user. The default handler for this signal will normally be
278			-- responsible for inserting the text, so by connecting to this
279			-- signal and then stopping the signal with gtk_signal_emit_stop(),
280			-- it is possible to modify the inserted text, or prevent it from
281			-- being inserted entirely.
282		do
283			connect (Current, insert_text_signal_name, $on_insert_text)
284		end
285
286	connect_agent_to_insert_text_signal (a_procedure: PROCEDURE [ANY, TUPLE [STRING, INTEGER, REFERENCE [INTEGER], GTK_EDITABLE]]) is
287			-- editable : 	the object which received the signal.
288			-- new_text : 	the new text to insert.
289			-- new_text_length : 	the length of the new text, in bytes,
290			--  or -1 if new_text is nul-terminated
291			-- position : 	the position, in characters, at which to insert the new text.
292			--  this is an in-out parameter. After the signal emission is finished,
293			--  it should point after the newly inserted text.
294		require
295			valid_procedure: a_procedure /= Void
296		local
297			insert_text_callback: INSERT_TEXT_CALLBACK
298		do
299			create insert_text_callback.make
300			insert_text_callback.connect (Current, a_procedure)
301		end
302
303end -- class GTK_EDITABLE