From a07dea88030a7f666f949e3f805a423d0631780a Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 28 Dec 2008 18:57:44 +0000 Subject: [PATCH] Merge docs inline svn path=/trunk/; revision=21955 --- ChangeLog | 4 + docs/reference/ChangeLog | 4 + docs/reference/gtk/tmpl/gtkeditable.sgml | 192 ++++++----------------- gtk/gtkeditable.c | 130 ++++++++++----- 4 files changed, 151 insertions(+), 179 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6a50a24627..dc48ea7d26 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2008-12-28 Matthias Clasen + + * gtk/gtkeditable.c: Merge docs inline. + 2008-12-28 Matthias Clasen * gtk/gtkhsv.c: diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index e93a6208b2..9bf976006a 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2008-12-28 Matthias Clasen + + * gtk/tmpl/gtkeditable.sgml: Merge docs inline. + 2008-12-27 Matthias Clasen * gtk/tmpl/gtkmessagedialog.sgml: diff --git a/docs/reference/gtk/tmpl/gtkeditable.sgml b/docs/reference/gtk/tmpl/gtkeditable.sgml index 2ecae68bbb..46cd5f5ad1 100644 --- a/docs/reference/gtk/tmpl/gtkeditable.sgml +++ b/docs/reference/gtk/tmpl/gtkeditable.sgml @@ -57,230 +57,142 @@ insert_text_handler (GtkEditable *editable, -The #GtkEditable structure contains the following fields. -(These fields should be considered read-only. They should -never be set by an application.) - - - - - - -#guint selection_start; -the starting position of the selected characters - in the widget. - - - -#guint selection_end; -the end position of the selected characters - in the widget. - - - -#guint editable; -a flag indicating whether or not the widget is -editable by the user. - - - - - - - - -Indicates that the user has changed the contents -of the widget. +The #GtkEditable structure is an opaque structure whose members +cannot be directly accessed. @editable: the object which received the signal. -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 gtk_signal_emit_stop(), 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() + -@editable: the object which received the signal. -@start_pos: the starting position. -@end_pos: the end position. +@editable: +@start_pos: +@end_pos: -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 gtk_signal_emit_stop(), it -is possible to modify the inserted text, or prevent -it from being inserted entirely. + -@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: 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. +@editable: +@new_text: +@new_text_length: +@position: + -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 the characters selected -will be those characters from @start_pos to the end -of the text. + -@editable: a #GtkEditable widget. -@start: the starting position. -@end: the end position. +@editable: +@start: +@end: -Gets the current selection bounds, if there is a selection. + -@editable: a #GtkEditable widget. -@start: location to store the starting position, or %NULL. -@end: location to store the end position, or %NULL. -@Returns: %TRUE if there is a selection. +@editable: +@start: +@end: +@Returns: -Inserts text at a given position. + -@editable: a #GtkEditable widget. -@new_text: the text to insert. -@new_text_length: the length of the text to insert, in bytes -@position: an inout parameter. The caller initializes it to - the position at which to insert the text. After the - call it points at the position after the newly - inserted text. +@editable: +@new_text: +@new_text_length: +@position: -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 the characters deleted -will be those characters from @start_pos to the end -of the text. + -@editable: a #GtkEditable widget. -@start_pos: the starting position. -@end_pos: the end position. +@editable: +@start_pos: +@end_pos: -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 the characters retrieved -will be those characters from @start_pos to the end -of the text. + -@editable: a #GtkEditable widget. -@start_pos: the starting position. -@end_pos: the end position. -@Returns: the characters in the indicated region. - The result must be freed with g_free() when - the application is finished with it. +@editable: +@start_pos: +@end_pos: +@Returns: -Causes the characters in the current selection to -be copied to the clipboard and then deleted from -the widget. + -@editable: a #GtkEditable widget. +@editable: -Causes the characters in the current selection to -be copied to the clipboard. + -@editable: a #GtkEditable widget. +@editable: -Causes the contents of the clipboard to be pasted into -the given widget at the current cursor position. + -@editable: a #GtkEditable widget. +@editable: -Deletes the current contents of the widgets selection and -disclaims the selection. + -@editable: a #GtkEditable widget. +@editable: -Sets the cursor position. + -@editable: a #GtkEditable widget. -@position: the position of the cursor. The cursor is displayed - before the character with the given (base 0) index - in the widget. The value must be less than or - equal to the number of characters in the widget. - A value of -1 indicates that the position should - be set after the last character in the entry. - Note that this position is in characters, not in - bytes. +@editable: +@position: -Retrieves the current cursor position. + -@editable: a #GtkEditable widget. -@Returns: the position of the cursor. The cursor is displayed - before the character with the given (base 0) index - in the widget. The value will be less than or - equal to the number of characters in the widget. - Note that this position is in characters, not in - bytes. +@editable: +@Returns: -Determines if the user can edit the text in the editable -widget or not. + -@editable: a #GtkEditable widget. -@is_editable: %TRUE if the user is allowed to edit the text - in the widget. +@editable: +@is_editable: diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c index 466516f835..37c29c1354 100644 --- a/gtk/gtkeditable.c +++ b/gtk/gtkeditable.c @@ -64,6 +64,25 @@ 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: 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, @@ -74,6 +93,23 @@ gtk_editable_base_init (gpointer g_class) 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, @@ -100,11 +136,14 @@ gtk_editable_base_init (gpointer g_class) * @editable: a #GtkEditable * @new_text: the text to append * @new_text_length: the length of the text in bytes, or -1 - * @position: position text will be inserted at + * @position: location of the position text will be inserted at * - * Appends @new_text_length bytes of @new_text to the contents of the widget, - * at position @position. Note that this position is in characters, not in bytes. - **/ + * 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. + */ void gtk_editable_insert_text (GtkEditable *editable, const gchar *new_text, @@ -126,9 +165,13 @@ 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 the characters deleted + * are those from @start_pos to the end of the text. + * + * Note that the positions are specified in characters, not bytes. + */ void gtk_editable_delete_text (GtkEditable *editable, gint start_pos, @@ -145,13 +188,17 @@ gtk_editable_delete_text (GtkEditable *editable, * @start_pos: start of text * @end_pos: end of text * - * Retreives the content of the editable between @start_pos and @end_pos. + * 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 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_pos, @@ -165,15 +212,16 @@ gtk_editable_get_chars (GtkEditable *editable, /** * 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) @@ -188,11 +236,12 @@ 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) { @@ -204,17 +253,17 @@ gtk_editable_get_position (GtkEditable *editable) /** * gtk_editable_get_selection_bounds: * @editable: a #GtkEditable - * @start_pos: beginning of selection - * @end_pos: end of selection + * @start_pos: location to store the starting position, or %NULL + * @end_pos: 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. + * + * 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, @@ -240,8 +289,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) { @@ -259,10 +308,14 @@ gtk_editable_delete_selection (GtkEditable *editable) * @start_pos: start of region * @end_pos: end of region * - * Selects the text between @start_pos and @end_pos. Both @start_pos and - * @end_pos are relative to the start of the content. Note that positions - * are specified in characters, not bytes. - **/ + * 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 the + * characters selected are those characters from @start_pos to + * the end of the text. + * + * Note that positions are specified in characters, not bytes. + */ void gtk_editable_select_region (GtkEditable *editable, gint start_pos, @@ -279,7 +332,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 +347,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 +362,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 +379,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 +399,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) {