X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkeditable.c;h=43dfd45564fc675cd5e31682d3fcb48230946ad1;hb=3c8e1c92a85b2e41161698f141747ced2c574f32;hp=16e839901a837a11402973c2b8b43639c0cd0ae8;hpb=bf5f9f7decc0f76ddef6a45ab91ad1df8c772efc;p=~andy%2Fgtk diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c index 16e839901..43dfd4556 100644 --- a/gtk/gtkeditable.c +++ b/gtk/gtkeditable.c @@ -12,9 +12,7 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library. If not, see . */ /* @@ -24,13 +22,55 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/** + * SECTION:gtkeditable + * @Short_description: Interface for text-editing widgets + * @Title: GtkEditable + * + * The #GtkEditable interface is an interface which should be implemented by + * text editing widgets, such as #GtkEntry and #GtkSpinButton. It contains functions + * for generically manipulating an editable widget, a large number of action + * signals used for key bindings, and several signals that an application can + * connect to to modify the behavior of a widget. + * + * As an example of the latter usage, by connecting + * the following handler to #GtkEditable::insert-text, an application + * can convert all entry into a widget into uppercase. + * + * + * Forcing entry to uppercase. + * + * #include <ctype.h> + * + * void + * insert_text_handler (GtkEditable *editable, + * const gchar *text, + * gint length, + * gint *position, + * gpointer data) + * { + * gchar *result = g_utf8_strup (text, length); + * + * g_signal_handlers_block_by_func (editable, + * (gpointer) insert_text_handler, data); + * gtk_editable_insert_text (editable, result, length, position); + * g_signal_handlers_unblock_by_func (editable, + * (gpointer) insert_text_handler, data); + * + * g_signal_stop_emission_by_name (editable, "insert_text"); + * + * g_free (result); + * } + * + * + */ + #include "config.h" #include #include "gtkeditable.h" #include "gtkmarshalers.h" #include "gtkintl.h" -#include "gtkalias.h" static void gtk_editable_base_init (gpointer g_class); @@ -45,7 +85,7 @@ gtk_editable_get_type (void) { const GTypeInfo editable_info = { - sizeof (GtkEditableClass), /* class_size */ + sizeof (GtkEditableInterface), /* class_size */ gtk_editable_base_init, /* base_init */ NULL, /* base_finalize */ }; @@ -64,29 +104,78 @@ gtk_editable_base_init (gpointer g_class) if (! initialized) { + /** + * GtkEditable::insert-text: + * @editable: the object which received the signal + * @new_text: the new text to insert + * @new_text_length: the length of the new text, in bytes, + * or -1 if new_text is nul-terminated + * @position: (inout) (type int): the position, in characters, + * at which to insert the new text. this is an in-out + * parameter. After the signal emission is finished, it + * should point after the newly inserted text. + * + * This signal is emitted when text is inserted into + * the widget by the user. The default handler for + * this signal will normally be responsible for inserting + * the text, so by connecting to this signal and then + * stopping the signal with g_signal_stop_emission(), it + * is possible to modify the inserted text, or prevent + * it from being inserted entirely. + */ g_signal_new (I_("insert-text"), GTK_TYPE_EDITABLE, G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (GtkEditableClass, insert_text), + G_STRUCT_OFFSET (GtkEditableInterface, insert_text), NULL, NULL, _gtk_marshal_VOID__STRING_INT_POINTER, G_TYPE_NONE, 3, G_TYPE_STRING, G_TYPE_INT, G_TYPE_POINTER); + + /** + * GtkEditable::delete-text: + * @editable: the object which received the signal + * @start_pos: the starting position + * @end_pos: the end position + * + * This signal is emitted when text is deleted from + * the widget by the user. The default handler for + * this signal will normally be responsible for deleting + * the text, so by connecting to this signal and then + * stopping the signal with g_signal_stop_emission(), it + * is possible to modify the range of deleted text, or + * prevent it from being deleted entirely. The @start_pos + * and @end_pos parameters are interpreted as for + * gtk_editable_delete_text(). + */ g_signal_new (I_("delete-text"), GTK_TYPE_EDITABLE, G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (GtkEditableClass, delete_text), + G_STRUCT_OFFSET (GtkEditableInterface, delete_text), NULL, NULL, _gtk_marshal_VOID__INT_INT, G_TYPE_NONE, 2, G_TYPE_INT, G_TYPE_INT); + /** + * GtkEditable::changed: + * @editable: the object which received the signal + * + * The ::changed signal is emitted at the end of a single + * user-visible operation on the contents of the #GtkEditable. + * + * E.g., a paste operation that replaces the contents of the + * selection will cause only one signal emission (even though it + * is implemented by first deleting the selection, then inserting + * the new content, and may cause multiple ::notify::text signals + * to be emitted). + */ g_signal_new (I_("changed"), GTK_TYPE_EDITABLE, G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (GtkEditableClass, changed), + G_STRUCT_OFFSET (GtkEditableInterface, changed), NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); @@ -99,12 +188,17 @@ gtk_editable_base_init (gpointer g_class) * gtk_editable_insert_text: * @editable: a #GtkEditable * @new_text: the text to append - * @new_text_length: the text to append - * @position: position text will be inserted at + * @new_text_length: the length of the text in bytes, or -1 + * @position: (inout): location of the position text will be inserted at + * + * Inserts @new_text_length bytes of @new_text into the contents of the + * widget, at position @position. + * + * Note that the position is in characters, not in bytes. + * The function updates @position to point after the newly inserted text. * - * Appends @new_text_length characters of @new_text to the contents of the widget, - * at position @position. Note that this position is in characters, not in bytes. - **/ + * Virtual: do_insert_text + */ void gtk_editable_insert_text (GtkEditable *editable, const gchar *new_text, @@ -117,7 +211,7 @@ gtk_editable_insert_text (GtkEditable *editable, if (new_text_length < 0) new_text_length = strlen (new_text); - GTK_EDITABLE_GET_CLASS (editable)->do_insert_text (editable, new_text, new_text_length, position); + GTK_EDITABLE_GET_IFACE (editable)->do_insert_text (editable, new_text, new_text_length, position); } /** @@ -126,9 +220,15 @@ gtk_editable_insert_text (GtkEditable *editable, * @start_pos: start position * @end_pos: end position * - * Deletes the content of the editable between @start_pos and @end_pos. - * Note that positions are specified in characters, not bytes. - **/ + * Deletes a sequence of characters. The characters that are deleted are + * those characters at positions from @start_pos up to, but not including + * @end_pos. If @end_pos is negative, then the characters deleted + * are those from @start_pos to the end of the text. + * + * Note that the positions are specified in characters, not bytes. + * + * Virtual: do_delete_text + */ void gtk_editable_delete_text (GtkEditable *editable, gint start_pos, @@ -136,51 +236,56 @@ gtk_editable_delete_text (GtkEditable *editable, { g_return_if_fail (GTK_IS_EDITABLE (editable)); - GTK_EDITABLE_GET_CLASS (editable)->do_delete_text (editable, start_pos, end_pos); + GTK_EDITABLE_GET_IFACE (editable)->do_delete_text (editable, start_pos, end_pos); } /** * gtk_editable_get_chars: * @editable: a #GtkEditable - * @start: start of text - * @end: end of text + * @start_pos: start of text + * @end_pos: end of text * - * Retreives the content of the editable between @start and @end. + * Retrieves a sequence of characters. The characters that are retrieved + * are those characters at positions from @start_pos up to, but not + * including @end_pos. If @end_pos is negative, then the characters + * retrieved are those characters from @start_pos to the end of the text. + * * Note that positions are specified in characters, not bytes. * * Return value: a pointer to the contents of the widget as a * string. This string is allocated by the #GtkEditable * implementation and should be freed by the caller. - **/ + */ gchar * gtk_editable_get_chars (GtkEditable *editable, - gint start, - gint end) + gint start_pos, + gint end_pos) { g_return_val_if_fail (GTK_IS_EDITABLE (editable), NULL); - return GTK_EDITABLE_GET_CLASS (editable)->get_chars (editable, start, end); + return GTK_EDITABLE_GET_IFACE (editable)->get_chars (editable, start_pos, end_pos); } /** * gtk_editable_set_position: * @editable: a #GtkEditable - * @position: the position of the cursor. The cursor is displayed - * before the character with the given (base 0) index in the editable. - * The value must be less than or equal to the number of characters - * in the editable. A value of -1 indicates that the position should - * be set after the last character of the editable. Note that this - * position is in characters, not in bytes. + * @position: the position of the cursor * * Sets the cursor position in the editable to the given value. - **/ + * + * The cursor is displayed before the character with the given (base 0) + * index in the contents of the editable. The value must be less than or + * equal to the number of characters in the editable. A value of -1 + * indicates that the position should be set after the last character + * of the editable. Note that @position is in characters, not in bytes. + */ void gtk_editable_set_position (GtkEditable *editable, gint position) { g_return_if_fail (GTK_IS_EDITABLE (editable)); - GTK_EDITABLE_GET_CLASS (editable)->set_position (editable, position); + GTK_EDITABLE_GET_IFACE (editable)->set_position (editable, position); } /** @@ -188,33 +293,34 @@ gtk_editable_set_position (GtkEditable *editable, * @editable: a #GtkEditable * * Retrieves the current position of the cursor relative to the start - * of the content of the editable. Note that this position is in characters, - * not in bytes. + * of the content of the editable. + * + * Note that this position is in characters, not in bytes. * * Return value: the cursor position - **/ + */ gint gtk_editable_get_position (GtkEditable *editable) { g_return_val_if_fail (GTK_IS_EDITABLE (editable), 0); - return GTK_EDITABLE_GET_CLASS (editable)->get_position (editable); + return GTK_EDITABLE_GET_IFACE (editable)->get_position (editable); } /** * gtk_editable_get_selection_bounds: * @editable: a #GtkEditable - * @start_pos: beginning of selection - * @end_pos: end of selection + * @start_pos: (out) (allow-none): location to store the starting position, or %NULL + * @end_pos: (out) (allow-none): location to store the end position, or %NULL * - * Retrieves the selection bound of the editable. @start_pos will be filled - * with the start of the selection and @end_pos with end. If no text was selected - * both will be identical and %FALSE will be returned. Note that positions are - * specified in characters, not bytes. + * Retrieves the selection bound of the editable. start_pos will be filled + * with the start of the selection and @end_pos with end. If no text was + * selected both will be identical and %FALSE will be returned. * - * Return value: %TRUE if an area is selected, %FALSE otherwise + * Note that positions are specified in characters, not bytes. * - **/ + * Return value: %TRUE if an area is selected, %FALSE otherwise + */ gboolean gtk_editable_get_selection_bounds (GtkEditable *editable, gint *start_pos, @@ -225,7 +331,7 @@ gtk_editable_get_selection_bounds (GtkEditable *editable, g_return_val_if_fail (GTK_IS_EDITABLE (editable), FALSE); - result = GTK_EDITABLE_GET_CLASS (editable)->get_selection_bounds (editable, &tmp_start, &tmp_end); + result = GTK_EDITABLE_GET_IFACE (editable)->get_selection_bounds (editable, &tmp_start, &tmp_end); if (start_pos) *start_pos = MIN (tmp_start, tmp_end); @@ -240,8 +346,8 @@ gtk_editable_get_selection_bounds (GtkEditable *editable, * @editable: a #GtkEditable * * Deletes the currently selected text of the editable. - * This call will not do anything if there is no selected text. - **/ + * This call doesn't do anything if there is no selected text. + */ void gtk_editable_delete_selection (GtkEditable *editable) { @@ -256,21 +362,27 @@ gtk_editable_delete_selection (GtkEditable *editable) /** * gtk_editable_select_region: * @editable: a #GtkEditable - * @start: start of region - * @end: end of region + * @start_pos: start of region + * @end_pos: end of region + * + * Selects a region of text. The characters that are selected are + * those characters at positions from @start_pos up to, but not + * including @end_pos. If @end_pos is negative, then the + * characters selected are those characters from @start_pos to + * the end of the text. + * + * Note that positions are specified in characters, not bytes. * - * Selects the text between @start and @end. Both @start and @end are - * relative to the start of the content. Note that positions are specified - * in characters, not bytes. - **/ + * Virtual: set_selection_bounds + */ void gtk_editable_select_region (GtkEditable *editable, - gint start, - gint end) + gint start_pos, + gint end_pos) { g_return_if_fail (GTK_IS_EDITABLE (editable)); - GTK_EDITABLE_GET_CLASS (editable)->set_selection_bounds (editable, start, end); + GTK_EDITABLE_GET_IFACE (editable)->set_selection_bounds (editable, start_pos, end_pos); } /** @@ -279,7 +391,7 @@ gtk_editable_select_region (GtkEditable *editable, * * Removes the contents of the currently selected content in the editable and * puts it on the clipboard. - **/ + */ void gtk_editable_cut_clipboard (GtkEditable *editable) { @@ -294,7 +406,7 @@ gtk_editable_cut_clipboard (GtkEditable *editable) * * Copies the contents of the currently selected content in the editable and * puts it on the clipboard. - **/ + */ void gtk_editable_copy_clipboard (GtkEditable *editable) { @@ -309,7 +421,7 @@ gtk_editable_copy_clipboard (GtkEditable *editable) * * Pastes the content of the clipboard to the current position of the * cursor in the editable. - **/ + */ void gtk_editable_paste_clipboard (GtkEditable *editable) { @@ -326,8 +438,7 @@ gtk_editable_paste_clipboard (GtkEditable *editable) * * Determines if the user can edit the text in the editable * widget or not. - * - **/ + */ void gtk_editable_set_editable (GtkEditable *editable, gboolean is_editable) @@ -347,7 +458,7 @@ gtk_editable_set_editable (GtkEditable *editable, * gtk_editable_set_editable(). * * Return value: %TRUE if @editable is editable. - **/ + */ gboolean gtk_editable_get_editable (GtkEditable *editable) { @@ -359,6 +470,3 @@ gtk_editable_get_editable (GtkEditable *editable) return value; } - -#define __GTK_EDITABLE_C__ -#include "gtkaliasdef.c"