<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtktextmark">
  <refnamediv>
    <refname>gtk.TextMark</refname>
    <refpurpose>a position in a textbuffer that is preserved across
textbuffer modifications</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.TextMark</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktextmark--set-visible">set_visible</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktextmark--get-visible">get_visible</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktextmark--get-name">get_name</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktextmark--get-deleted">get_deleted</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktextmark--get-buffer">get_buffer</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktextmark--get-left-gravity">get_left_gravity</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtktextmark">gtk.TextMark</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtktextmark">
    <title>gtk.TextMark Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtktextmark"><classname>gtk.TextMark</classname></link> is
like a bookmark in a textbuffer - it preserves a position in the text. You
can get an iterator corresponding to a textmark by using the <link
linkend="method-gtktextbuffer--get-iter-at-mark"><methodname>gtk.TextBuffer.get_iter_at_mark</methodname>()</link> 
method. Unlike iterators, textmarks remain valid across buffer modifications
(e.g. when text is inserted or deleted). When text containing a textmark is
deleted, the textmark remains in the position originally occupied by the
deleted text. When text is inserted at a textmark, a textmark with left
gravity will be moved to the beginning of the newly-inserted text, and a
textmark with right gravity will be moved to the end. Textmarks optionally
have names that can be used to avoid passing the <link
linkend="class-gtktextmark"><classname>gtk.TextMark</classname></link>
object around. Textmarks are typically created using the <link
linkend="method-gtktextbuffer--create-mark"><methodname>gtk.TextBuffer.create_mark</methodname>()</link> 
method. A <link
linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link>
has two built-in <link
linkend="class-gtktextmark"><classname>gtk.TextMark</classname></link>
objects named: <literal>insert</literal> and
<literal>selection_bound</literal> which refer to the insertion point and
the boundary of the selection (these may refer to the same location).</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

  <refsect2 id="method-gtktextmark--set-visible">
      <title>gtk.TextMark.set_visible</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_visible</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the textmark is
visible</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para> The <methodname>set_visible</methodname>() method sets the
visibility of the textmark to the value specified by
<parameter>setting</parameter>. If <parameter>setting</parameter> is
<literal>True</literal> the textmark will be visible as a vertical bar. The
insertion point is normally visible but most textmarks are not visible by
default. The text widget uses a visible textmark to indicate where a drop
will occur when dragging-and-dropping text.</para>

    </refsect2>

    <refsect2 id="method-gtktextmark--get-visible">
      <title>gtk.TextMark.get_visible</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_visible</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the textmark is
visible</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_visible</methodname>() method returns
<literal>True</literal> if the textmark is visible (i.e. a vertical bar is
displayed for it)</para>

    </refsect2>

    <refsect2 id="method-gtktextmark--get-name">
      <title>gtk.TextMark.get_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_name</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the textmark name or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_name</methodname>() method returns the
textmark name or <literal>None</literal> if the textmark is
anonymous.</para>

    </refsect2>

    <refsect2 id="method-gtktextmark--get-deleted">
      <title>gtk.TextMark.get_deleted</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_deleted</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the textmark is
deleted</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_deleted</methodname>() method returns
<literal>True</literal> if the textmark has been removed from its textbuffer
with <link
linkend="method-gtktextbuffer--delete-mark"><methodname>gtk.TextBuffer.delete_mark</methodname>()</link>. 
Textmarks can't be used once deleted.</para>

    </refsect2>

    <refsect2 id="method-gtktextmark--get-buffer">
      <title>gtk.TextMark.get_buffer</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_buffer</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the textmark's <link
linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_buffer</methodname>() method returns the
<link
linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link>
object the textmark is located inside, or <literal>None</literal> if the
textmark is deleted.</para>

    </refsect2>

    <refsect2 id="method-gtktextmark--get-left-gravity">
      <title>gtk.TextMark.get_left_gravity</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_left_gravity</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the textmark has
left gravity</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_left_gravity</methodname>() method returns
True if the textmark has left gravity.</para>

    </refsect2>

  </refsect1>

</refentry>
