<refentry id="gtk-GtkEditable">
<refmeta>
<refentrytitle>GtkEditable</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkEditable</refname><refpurpose>Base class for text-editing widgets.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gtk/gtk.h&gt;


struct      <link linkend="GtkEditable">GtkEditable</link>;
void        <link linkend="gtk-editable-select-region">gtk_editable_select_region</link>      (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> start,
                                             <link linkend="gint">gint</link> end);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-editable-get-selection-bounds">gtk_editable_get_selection_bounds</link>
                                            (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> *start,
                                             <link linkend="gint">gint</link> *end);
void        <link linkend="gtk-editable-insert-text">gtk_editable_insert_text</link>        (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             const <link linkend="gchar">gchar</link> *new_text,
                                             <link linkend="gint">gint</link> new_text_length,
                                             <link linkend="gint">gint</link> *position);
void        <link linkend="gtk-editable-delete-text">gtk_editable_delete_text</link>        (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> start_pos,
                                             <link linkend="gint">gint</link> end_pos);
<link linkend="gchar">gchar</link>*      <link linkend="gtk-editable-get-chars">gtk_editable_get_chars</link>          (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> start_pos,
                                             <link linkend="gint">gint</link> end_pos);
void        <link linkend="gtk-editable-cut-clipboard">gtk_editable_cut_clipboard</link>      (<link linkend="GtkEditable">GtkEditable</link> *editable);
void        <link linkend="gtk-editable-copy-clipboard">gtk_editable_copy_clipboard</link>     (<link linkend="GtkEditable">GtkEditable</link> *editable);
void        <link linkend="gtk-editable-paste-clipboard">gtk_editable_paste_clipboard</link>    (<link linkend="GtkEditable">GtkEditable</link> *editable);
void        <link linkend="gtk-editable-delete-selection">gtk_editable_delete_selection</link>   (<link linkend="GtkEditable">GtkEditable</link> *editable);
void        <link linkend="gtk-editable-set-position">gtk_editable_set_position</link>       (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> position);
<link linkend="gint">gint</link>        <link linkend="gtk-editable-get-position">gtk_editable_get_position</link>       (<link linkend="GtkEditable">GtkEditable</link> *editable);
void        <link linkend="gtk-editable-set-editable">gtk_editable_set_editable</link>       (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gboolean">gboolean</link> is_editable);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-editable-get-editable">gtk_editable_get_editable</link>       (<link linkend="GtkEditable">GtkEditable</link> *editable);


</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GtkEditable">GtkEditable</link> class is a base class for widgets
for editing text, such as <link linkend="GtkEntry">GtkEntry</link> and <link linkend="GtkText">GtkText</link>. It
cannot be instantiated by itself. The editable
class contains functions for generically manipulating
an editable widget, a large number of action signals
used for key bindings, and several signals that
an application can connect to to modify the behavior
of a widget. 
</para>

<para>
As an example of the latter usage, by connecting
the following handler to "insert_text", an application
can convert all entry into a widget into uppercase.

<example>
<title>Forcing entry to uppercase.</title>
<programlisting>
<link linkend="include">include</link> &lt;ctype.h&gt;

void
insert_text_handler (GtkEditable *editable,
                     const gchar *text,
                     gint         length,
                     gint        *position,
                     gpointer     data)
{
  int i;
  gchar *result = g_new (gchar, length);

  for (i = 0; i &lt; length; i++)
    result[i] = islower (text[i]) ? toupper (text[i]) : text[i];

  g_signal_handlers_block_by_func (GTK_OBJECT (editable), 
				   insert_text_handler, data);
  gtk_editable_insert_text (editable, result, length, position);
  g_signal_handlers_unblock_by_func (GTK_OBJECT (editable), 
                                     insert_text_handler, data);

  g_signal_stop_emission_by_name (GTK_OBJECT (editable), "insert_text"); 

  g_free (result);
}
</programlisting>
</example>
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkEditable">struct GtkEditable</title>
<programlisting>struct GtkEditable;</programlisting>
<para>
The <link linkend="GtkEditable">GtkEditable</link> 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><link linkend="guint">guint</link> selection_start;</entry>
<entry>the starting position of the selected characters 
 in the widget.</entry>
</row>

<row>
<entry><link linkend="guint">guint</link> selection_end;</entry>
<entry>the end position of the selected characters 
 in the widget.</entry>
</row>

<row>
<entry><link linkend="guint">guint</link> editable;</entry>
<entry>a flag indicating whether or not the widget is
editable by the user.</entry>
</row>

</tbody></tgroup></informaltable>
</para></refsect2>
<refsect2>
<title><anchor id="gtk-editable-select-region">gtk_editable_select_region ()</title>
<programlisting>void        gtk_editable_select_region      (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> start,
                                             <link linkend="gint">gint</link> end);</programlisting>
<para>
Selects a region of text. The characters that
are selected are those characters at positions from
<parameter>start_pos</parameter> up to, but not including <parameter>end_pos</parameter>. If 
<parameter>end_pos</parameter> is negative, then the the characters selected
will be those characters from <parameter>start_pos</parameter> to the end
of the text.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>start</parameter>&nbsp;:</entry>
<entry>the starting position.
</entry></row>
<row><entry align="right"><parameter>end</parameter>&nbsp;:</entry>
<entry>the end position.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-get-selection-bounds">gtk_editable_get_selection_bounds ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_editable_get_selection_bounds
                                            (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> *start,
                                             <link linkend="gint">gint</link> *end);</programlisting>
<para>
Gets the current selection bounds, if there is a selection.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>start</parameter>&nbsp;:</entry>
<entry>location to store the starting position, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><parameter>end</parameter>&nbsp;:</entry>
<entry>location to store the end position, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if there is a selection.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-insert-text">gtk_editable_insert_text ()</title>
<programlisting>void        gtk_editable_insert_text        (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             const <link linkend="gchar">gchar</link> *new_text,
                                             <link linkend="gint">gint</link> new_text_length,
                                             <link linkend="gint">gint</link> *position);</programlisting>
<para>
Inserts text at a given position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>new_text</parameter>&nbsp;:</entry>
<entry>the text to insert.
</entry></row>
<row><entry align="right"><parameter>new_text_length</parameter>&nbsp;:</entry>
<entry>the length of the text to insert, in bytes
</entry></row>
<row><entry align="right"><parameter>position</parameter>&nbsp;:</entry>
<entry>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.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-delete-text">gtk_editable_delete_text ()</title>
<programlisting>void        gtk_editable_delete_text        (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> start_pos,
                                             <link linkend="gint">gint</link> end_pos);</programlisting>
<para>
Deletes a sequence of characters. The characters that
are deleted are those characters at positions from
<parameter>start_pos</parameter> up to, but not including <parameter>end_pos</parameter>. If 
<parameter>end_pos</parameter> is negative, then the the characters deleted
will be those characters from <parameter>start_pos</parameter> to the end
of the text.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>start_pos</parameter>&nbsp;:</entry>
<entry>the starting position.
</entry></row>
<row><entry align="right"><parameter>end_pos</parameter>&nbsp;:</entry>
<entry>the end position.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-get-chars">gtk_editable_get_chars ()</title>
<programlisting><link linkend="gchar">gchar</link>*      gtk_editable_get_chars          (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> start_pos,
                                             <link linkend="gint">gint</link> end_pos);</programlisting>
<para>
Retrieves a sequence of characters. The characters that
are retrieved are those characters at positions from
<parameter>start_pos</parameter> up to, but not including <parameter>end_pos</parameter>. If 
<parameter>end_pos</parameter> is negative, then the the characters retrieved
will be those characters from <parameter>start_pos</parameter> to the end
of the text.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>start_pos</parameter>&nbsp;:</entry>
<entry>the starting position.
</entry></row>
<row><entry align="right"><parameter>end_pos</parameter>&nbsp;:</entry>
<entry>the end position.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the characters in the indicated region.
          The result must be freed with <link linkend="g-free">g_free</link>() when
          the application is finished with it.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-cut-clipboard">gtk_editable_cut_clipboard ()</title>
<programlisting>void        gtk_editable_cut_clipboard      (<link linkend="GtkEditable">GtkEditable</link> *editable);</programlisting>
<para>
Causes the characters in the current selection to
be copied to the clipboard and then deleted from
the widget.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-copy-clipboard">gtk_editable_copy_clipboard ()</title>
<programlisting>void        gtk_editable_copy_clipboard     (<link linkend="GtkEditable">GtkEditable</link> *editable);</programlisting>
<para>
Causes the characters in the current selection to
be copied to the clipboard.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-paste-clipboard">gtk_editable_paste_clipboard ()</title>
<programlisting>void        gtk_editable_paste_clipboard    (<link linkend="GtkEditable">GtkEditable</link> *editable);</programlisting>
<para>
Causes the contents of the clipboard to be pasted into
the given widget at the current cursor position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-delete-selection">gtk_editable_delete_selection ()</title>
<programlisting>void        gtk_editable_delete_selection   (<link linkend="GtkEditable">GtkEditable</link> *editable);</programlisting>
<para>
Deletes the current contents of the widgets selection and
disclaims the selection.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-set-position">gtk_editable_set_position ()</title>
<programlisting>void        gtk_editable_set_position       (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gint">gint</link> position);</programlisting>
<para>
Sets the cursor position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>position</parameter>&nbsp;:</entry>
<entry>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.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-get-position">gtk_editable_get_position ()</title>
<programlisting><link linkend="gint">gint</link>        gtk_editable_get_position       (<link linkend="GtkEditable">GtkEditable</link> *editable);</programlisting>
<para>
Retrieves the current cursor position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>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.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-set-editable">gtk_editable_set_editable ()</title>
<programlisting>void        gtk_editable_set_editable       (<link linkend="GtkEditable">GtkEditable</link> *editable,
                                             <link linkend="gboolean">gboolean</link> is_editable);</programlisting>
<para>
Determines if the user can edit the text in the editable
widget or not.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkEditable">GtkEditable</link> widget.
</entry></row>
<row><entry align="right"><parameter>is_editable</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> if the user is allowed to edit the text
  in the widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-editable-get-editable">gtk_editable_get_editable ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_editable_get_editable       (<link linkend="GtkEditable">GtkEditable</link> *editable);</programlisting>
<para>
Retrieves whether <parameter>editable</parameter> is editable. See
<link linkend="gtk-editable-set-editable">gtk_editable_set_editable</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>editable</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkEditable">GtkEditable</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>editable</parameter> is editable.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
