<?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-gtkentrybuffer">
  <refnamediv>
    <refname>gtk.EntryBuffer</refname>
    <refpurpose>stores text for display in a <link linkend="class-gtkentry"><classname>gtk.Entry</classname></link> (new in PyGTK 2.22)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.EntryBuffer</classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkentrybuffer">gtk.EntryBuffer</link></methodname>
        <methodparam><parameter role="keyword">initial_chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_initial_chars</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--get-bytes">get_bytes</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--get-length">get_length</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--set-text">set_text</link></methodname>
        <methodparam><parameter role="keyword">chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--get-text">get_text</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--set-max-length">set_max_length</link></methodname>
        <methodparam><parameter role="keyword">max_length</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--get-max-length">get_max_length</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--insert-text">insert_text</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--delete-text">delete_text</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--emit-inserted-text">emit_inserted_text</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkentrybuffer--emit-deleted-text">emit_deleted_text</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkentrybuffer">gtk.EntryBuffer</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkentrybuffer">
    <title>gtk.EntryBuffer Properties</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
        <tgroup cols="3">
          <colspec column="1" colwidth="1in"/>
          <colspec column="2" colwidth="1in"/>
          <colspec column="3" colwidth="3.5in"/>
          <tbody>
            <row valign="top">
              <entry>"length"</entry>
              <entry>Read</entry>
              <entry>The length (in characters) of the text in buffer. Allowed values: &lt;=65535. Default value: 0.</entry>
            </row>

            <row valign="top">
              <entry>"max-length"</entry>
              <entry>Read/Write</entry>
              <entry>The maximum length (in characters) of the text in the buffer. Allowed values: &lt;=65535. Default value: 0.</entry>
            </row>

            <row valign="top">
              <entry>"text"</entry>
              <entry>Read/Write</entry>
              <entry>The contents of the buffer. Default value: "".</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkentrybuffer">
    <title>gtk.EntryBuffer Signal Prototypes</title>

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

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkentrybuffer--deleted-text">deleted-text</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>buffer</parameter></methodparam>
            <methodparam><parameter>position</parameter></methodparam>
            <methodparam><parameter>n_chars</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkentrybuffer--inserted-text">inserted-text</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>buffer</parameter></methodparam>
            <methodparam><parameter>position</parameter></methodparam>
            <methodparam><parameter>chars</parameter></methodparam>
            <methodparam><parameter>n_chars</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link> class contains the actual text displayed in a
    <link linkend="class-gtkentry"><classname>gtk.Entry</classname></link> widget.</para>

    <para>A single <link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link> object can be shared by multiple
    <link linkend="class-gtkentry"><classname>gtk.Entry</classname></link> widgets which will then share the same text content, but not the cursor
    position, visibility attributes, icon etc.</para>

    <para><link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link> may be derived from. Such a derived class might allow
    text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could
    integrate with an application's concept of undo/redo.</para>

    </refsect1>

  <refsect1 id="constructor-gtkentrybuffer">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
      <methodname>gtk.EntryBuffer</methodname>
      <methodparam><parameter role="keyword">initial_chars</parameter></methodparam>
      <methodparam><parameter role="keyword">n_initial_chars</parameter></methodparam>
    </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
        <term><parameter role="keyword">initial_chars</parameter>&nbsp;:</term>
        <listitem><simpara>initial buffer text, or <literal>None</literal>.</simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter role="keyword">n_initial_chars</parameter>&nbsp;:</term>
        <listitem><simpara>number of characters in <parameter>initial_chars</parameter>, or -1.</simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis>Returns</emphasis>&nbsp;:</term>
        <listitem><simpara>a new <link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link>.</simpara></listitem>
      </varlistentry>
    </variablelist>

      <note>
        <para>This constructor is available in PyGTK 2.22 and above.</para>
      </note>

    <para>Creates a new <link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link> object.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkentrybuffer--get-bytes">
      <title>gtk.EntryBuffer.get_bytes</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_bytes</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the byte length of the buffer.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_bytes</methodname>() method retrieves the length in bytes of the buffer.
      See <link linkend="method-gtkentrybuffer--get-length"><methodname>gtk.EntryBuffer.get_length</methodname></link>().</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--get-length">
      <title>gtk.EntryBuffer.get_length</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_length</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the number of characters in the buffer.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_length</methodname>() method retrieves the length in characters of the buffer.</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--set-text">
      <title>gtk.EntryBuffer.set_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_text</methodname>
        <methodparam><parameter role="keyword">chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">chars</parameter>&nbsp;:</term>
          <listitem><simpara>the new text</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the number of characters, or -1</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>set_text</methodname>() method sets the text in the buffer.</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--get-text">
      <title>gtk.EntryBuffer.get_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_text</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the contents of the buffer.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_text</methodname>() method retrieves the contents of the buffer.</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--get-max-length">
      <title>gtk.EntryBuffer.set_max_length</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_max_length</methodname>
        <methodparam><parameter role="keyword">max_length</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">max_length</parameter>&nbsp;:</term>
          <listitem><simpara>the maximum length of the entry buffer, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>set_max_length</methodname>() sets the maximum allowed length of the contents of the buffer.
      If the current contents are longer than the given length, then they will be truncated to fit.</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--set-max-length">
      <title>gtk.EntryBuffer.get_max_length</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_max_length</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the maximum allowed number of characters in the entry buffer, or 0 if there is no maximum.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_max_length</methodname>() method retrieves the maximum allowed length of the text in buffer.
      See <link linkend="method-gtkentrybuffer--set-max-length"><methodname>gtk.EntryBuffer.set_max_length</methodname></link>().</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--insert-text">
      <title>gtk.EntryBuffer.insert_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>insert_text</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>the position at which to insert text.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">chars</parameter>&nbsp;:</term>
          <listitem><simpara>the text to insert into the buffer.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the length of the text in characters, or -1.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>insert_text</methodname>() method inserts n_chars characters of chars into the contents of the buffer, at position position.</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--delete-text">
      <title>gtk.EntryBuffer.delete_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>delete_text</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>the position at which to delete text.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the number of characters to delete.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>delete_text</methodname>() method deletes a sequence of characters from the buffer. n_chars characters are deleted starting at position.
      If n_chars is negative, then all characters until the end of the text are deleted. .</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--emit-inserted-text">
      <title>gtk.EntryBuffer.emit_inserted_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>emit_inserted_text</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">chars</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>the position at which text was inserted.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">chars</parameter>&nbsp;:</term>
          <listitem><simpara>the text that was inserted.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the number of characters inserted.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>emit_inserted_text</methodname>() method can be used when subclassing
      <link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkentrybuffer--emit-deleted-text">
      <title>gtk.EntryBuffer.emit_deleted_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>emit_deleted_text</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>the position at which text was deleted.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the number of characters deleted.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>emit_deleted_text</methodname>() method can be used when subclassing
      <link linkend="class-gtkentrybuffer"><classname>gtk.EntryBuffer</classname></link>.</para>

    </refsect2>

   </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkentrybuffer--deleted-text">
      <title>The "deleted-text" gtk.EntryBuffer Signal</title>

      <programlisting><methodsynopsis language="python">
        <methodname>callback</methodname>
        <methodparam><parameter>buffer</parameter></methodparam>
        <methodparam><parameter>position</parameter></methodparam>
        <methodparam><parameter>n_chars</parameter></methodparam>
        <methodparam><parameter>user_param1</parameter></methodparam>
        <methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>buffer</parameter>&nbsp;:</term>
          <listitem><simpara>the buffer that received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>position</parameter>&nbsp;:</term>
          <listitem><simpara>the the position the text was deleted at</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the number of characters that were deleted</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified with the <link linkend="method-gobject--connect"><methodname>connect</methodname>()</link> method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The "activate" signal is emitted after text is deleted from the buffer.</para>

    </refsect2>

    <refsect2 id="signal-gtkentrybuffer--inserted-text">
      <title>The "inserted-text" gtk.EntryBuffer Signal</title>

      <programlisting><methodsynopsis language="python">
        <methodname>callback</methodname>
        <methodparam><parameter>buffer</parameter></methodparam>
        <methodparam><parameter>position</parameter></methodparam>
        <methodparam><parameter>chars</parameter></methodparam>
        <methodparam><parameter>n_chars</parameter></methodparam>
        <methodparam><parameter>user_param1</parameter></methodparam>
        <methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>buffer</parameter>&nbsp;:</term>
          <listitem><simpara>the buffer that received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>position</parameter>&nbsp;:</term>
          <listitem><simpara>the position the text was inserted at</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>chars</parameter>&nbsp;:</term>
          <listitem><simpara>the text that was inserted</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>n_chars</parameter>&nbsp;:</term>
          <listitem><simpara>the number of characters that were inserted</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified with the <link linkend="method-gobject--connect"><methodname>connect</methodname>()</link> method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The "activate" signal is emitted after text is inserted into the buffer. </para>

    </refsect2>

  </refsect1>

</refentry>
