]> Pileus Git - ~andy/gtk/blobdiff - gtk/gtktextmark.c
Minor doc cleanup
[~andy/gtk] / gtk / gtktextmark.c
index febec6b4b35a80c9e8502b665fa32e65551b5cd9..33b0649a6f66f050b9e73b03b07ec16bb38b4efc 100644 (file)
  */
 
 #define GTK_TEXT_USE_INTERNAL_UNSUPPORTED_API
-#include <config.h>
+#include "config.h"
 #include "gtktextbtree.h"
 #include "gtkprivate.h"
 #include "gtkintl.h"
-#include "gtkalias.h"
+
+
+/**
+ * SECTION:gtktextmark
+ * @Short_description: A position in the buffer preserved across buffer modifications
+ * @Title: GtkTextMark
+ *
+ * You may wish to begin by reading the <link linkend="TextWidget">text widget
+ * conceptual overview</link> which gives an overview of all the objects and data
+ * types related to the text widget and how they work together.
+ *
+ * A #GtkTextMark is like a bookmark in a text buffer; it preserves a position in
+ * the text. You can convert the mark to an iterator using
+ * gtk_text_buffer_get_iter_at_mark(). Unlike iterators, marks remain valid across
+ * buffer mutations, because their behavior is defined when text is inserted or
+ * deleted. When text containing a mark is deleted, the mark remains in the
+ * position originally occupied by the deleted text. When text is inserted at a
+ * mark, a mark with <firstterm>left gravity</firstterm> will be moved to the
+ * beginning of the newly-inserted text, and a mark with <firstterm>right
+ * gravity</firstterm> will be moved to the end.
+ *
+ * <footnote>
+ * "left" and "right" here refer to logical direction (left is the toward the start
+ * of the buffer); in some languages such as Hebrew the logically-leftmost text is
+ * not actually on the left when displayed.
+ * </footnote>
+ *
+ * Marks are reference counted, but the reference count only controls the validity
+ * of the memory; marks can be deleted from the buffer at any time with
+ * gtk_text_buffer_delete_mark(). Once deleted from the buffer, a mark is
+ * essentially useless.
+ *
+ * Marks optionally have names; these can be convenient to avoid passing the
+ * #GtkTextMark object around.
+ *
+ * Marks are typically created using the gtk_text_buffer_create_mark() function.
+ */
+
 
 static void gtk_text_mark_set_property (GObject         *object,
                                        guint            prop_id,
@@ -188,7 +225,7 @@ gtk_text_mark_get_property (GObject    *object,
 
 /**
  * gtk_text_mark_new:
- * @name: mark name or %NULL
+ * @name: (allow-none): mark name or %NULL
  * @left_gravity: whether the mark should have left gravity
  *
  * Creates a text mark. Add it to a buffer using gtk_text_buffer_add_mark().
@@ -220,7 +257,7 @@ gtk_text_mark_new (const gchar *name,
  * @mark: a #GtkTextMark
  * 
  * Returns %TRUE if the mark is visible (i.e. a cursor is displayed
- * for it)
+ * for it).
  * 
  * Return value: %TRUE if visible
  **/
@@ -282,9 +319,9 @@ gtk_text_mark_get_deleted (GtkTextMark *mark)
  * @mark: a #GtkTextMark
  * 
  * Gets the buffer this mark is located inside,
- * or NULL if the mark is deleted.
- * 
- * Return value: the mark's #GtkTextBuffer
+ * or %NULL if the mark is deleted.
+ *
+ * Return value: (transfer none): the mark's #GtkTextBuffer
  **/
 GtkTextBuffer*
 gtk_text_mark_get_buffer (GtkTextMark *mark)
@@ -490,6 +527,3 @@ mark_segment_check_func (GtkTextLineSegment *seg,
   if (seg->body.mark.line != line)
     g_error ("mark_segment_check_func: seg->body.mark.line bogus");
 }
-
-#define __GTK_TEXT_MARK_C__
-#include "gtkaliasdef.c"