GNOME.org
 

gtk+ r21955 - in trunk: . docs/reference docs/reference/gtk/tmpl gtk

Author: matthiasc
Date: Sun Dec 28 18:57:44 2008
New Revision: 21955
URL: http://svn.gnome.org/viewvc/gtk+?rev=21955&view=rev

Log:
Merge docs inline


Modified:
   trunk/ChangeLog
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/gtk/tmpl/gtkeditable.sgml
   trunk/gtk/gtkeditable.c

Modified: trunk/docs/reference/gtk/tmpl/gtkeditable.sgml
==============================================================================
--- trunk/docs/reference/gtk/tmpl/gtkeditable.sgml	(original)
+++ trunk/docs/reference/gtk/tmpl/gtkeditable.sgml	Sun Dec 28 18:57:44 2008
@@ -57,230 +57,142 @@
 
 <!-- ##### STRUCT GtkEditable ##### -->
 <para>
-The #GtkEditable structure contains the following fields.
-(These fields should be considered read-only. They should
-never be set by an application.)
-
-<informaltable pgwide="1" frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>#guint selection_start;</entry>
-<entry>the starting position of the selected characters 
- in the widget.</entry>
-</row>
-
-<row>
-<entry>#guint selection_end;</entry>
-<entry>the end position of the selected characters 
- in the widget.</entry>
-</row>
-
-<row>
-<entry>#guint editable;</entry>
-<entry>a flag indicating whether or not the widget is
-editable by the user.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-
-<!-- ##### SIGNAL GtkEditable::changed ##### -->
-<para>
-Indicates that the user has changed the contents
-of the widget.
+The #GtkEditable structure is an opaque structure whose members 
+cannot be directly accessed.
 </para>
 
 @editable: the object which received the signal.
 
 <!-- ##### SIGNAL GtkEditable::delete-text ##### -->
 <para>
-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()
+
 </para>
 
- editable: the object which received the signal.
- start_pos: the starting position.
- end_pos: the end position.
+ editable: 
+ start_pos: 
+ end_pos: 
 
 <!-- ##### SIGNAL GtkEditable::insert-text ##### -->
 <para>
-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.
+
 </para>
 
- 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:
+
 
 <!-- ##### FUNCTION gtk_editable_select_region ##### -->
 <para>
-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.
+
 </para>
 
- editable: a #GtkEditable widget.
- start: the starting position.
- end: the end position.
+ editable: 
+ start: 
+ end: 
 
 
 <!-- ##### FUNCTION gtk_editable_get_selection_bounds ##### -->
 <para>
-Gets the current selection bounds, if there is a selection.
+
 </para>
 
- 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:
 
 
 <!-- ##### FUNCTION gtk_editable_insert_text ##### -->
 <para>
-Inserts text at a given position.
+
 </para>
 
- 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: 
 
 
 <!-- ##### FUNCTION gtk_editable_delete_text ##### -->
 <para>
-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.
+
 </para>
 
- editable: a #GtkEditable widget.
- start_pos: the starting position.
- end_pos: the end position.
+ editable: 
+ start_pos: 
+ end_pos: 
 
 
 <!-- ##### FUNCTION gtk_editable_get_chars ##### -->
 <para>
-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.
+
 </para>
 
- 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: 
 
 
 <!-- ##### FUNCTION gtk_editable_cut_clipboard ##### -->
 <para>
-Causes the characters in the current selection to
-be copied to the clipboard and then deleted from
-the widget.
+
 </para>
 
- editable: a #GtkEditable widget.
+ editable:
 
 
 <!-- ##### FUNCTION gtk_editable_copy_clipboard ##### -->
 <para>
-Causes the characters in the current selection to
-be copied to the clipboard.
+
 </para>
 
- editable: a #GtkEditable widget.
+ editable: 
 
 
 <!-- ##### FUNCTION gtk_editable_paste_clipboard ##### -->
 <para>
-Causes the contents of the clipboard to be pasted into
-the given widget at the current cursor position.
+
 </para>
 
- editable: a #GtkEditable widget.
+ editable: 
 
 
 <!-- ##### FUNCTION gtk_editable_delete_selection ##### -->
 <para>
-Deletes the current contents of the widgets selection and
-disclaims the selection.
+
 </para>
 
- editable: a #GtkEditable widget.
+ editable: 
 
 
 <!-- ##### FUNCTION gtk_editable_set_position ##### -->
 <para>
-Sets the cursor position.
+
 </para>
 
- 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: 
 
 
 <!-- ##### FUNCTION gtk_editable_get_position ##### -->
 <para>
-Retrieves the current cursor position.
+
 </para>
 
- 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: 
 
 
 <!-- ##### FUNCTION gtk_editable_set_editable ##### -->
 <para>
-Determines if the user can edit the text in the editable
-widget or not.
+
 </para>
 
- editable: a #GtkEditable widget.
- is_editable: %TRUE if the user is allowed to edit the text
-  in the widget.
+ editable: 
+ is_editable:
 
 
 <!-- ##### FUNCTION gtk_editable_get_editable ##### -->

Modified: trunk/gtk/gtkeditable.c
==============================================================================
--- trunk/gtk/gtkeditable.c	(original)
+++ trunk/gtk/gtkeditable.c	Sun Dec 28 18:57:44 2008
@@ -64,6 +64,25 @@
 
   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 @@
 		    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 @@
  * @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
+ *
+ * Inserts @new_text_length bytes of @new_text into the contents of the 
+ * widget, at position @position. 
  *
- * 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.
- **/
+ * 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 @@
  * @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 @@
  * @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_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 @@
  * @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_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. 
  *
- * 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,
@@ -240,8 +289,8 @@
  * @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 @@
  * @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 @@
  *
  * 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 @@
  *
  * 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 @@
  *
  * 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 @@
  *
  * 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().
  *
  * Return value: %TRUE if @editable is editable.
- **/
+ */
 gboolean
 gtk_editable_get_editable (GtkEditable *editable)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]