<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="entry.py" xml:lang="ca">
  <info>
    <title type="text">Entry (Python)</title>
    <link type="guide" xref="beginner.py#entry"/>
    <revision version="0.2" date="2012-06-23" status="draft"/>

    <credit type="author copyright editor">
      <name>Marta Maria Casetti</name>
      <email/>
      <years>2012</years>
    </credit>

    <credit type="author copyright">
      <name>Sebastian Pölsterl</name>
      <email>sebp@k-d-w.org</email>
      <years>2011</years>
    </credit>
    <desc>A single line text entry field</desc>
  </info>

  <title>Entry</title>
  <media type="image" mime="image/png" src="media/entry.png"/>
  <p>This application greets you in the terminal with the name you provide.</p>

  <links type="section"/>

  <section id="code">
  <title>Code used to generate this example</title>
    <code mime="text/x-python" style="numbered"><xi:include href="samples/entry.py" parse="text"><xi:fallback/></xi:include></code>
  </section>

  <section id="methods">
    <title>Useful methods for an Entry widget</title>
    <p>For an explanation of signals and callback functions, see <link xref="signals-callbacks.py">this page</link>. Some of the signals that a Gtk.Entry widget can emit are: <code>"activate"</code> (emitted when the user activates the Entry key); <code>"backspace"</code> (emitted when the user activates the Backspace or Shift-Backspace keys); <code>"copy-clipboard"</code> (Ctrl-c and Ctrl-Insert); <code>"paste-clipboard"</code> (Ctrl-v and Shift-Insert); <code>"delete-from-cursor"</code> (Delete, for deleting a character; Ctrl-Delete, for deleting a word); <code>"icon-press"</code> (emitted when the user clicks an activable icon); <code>"icon-release"</code> (emitted on the button release from a mouse click over an activable icon);  <code>"insert-at-cursor"</code> (emitted when the user initiates the insertion of a fixed string at the cursor); <code>"move-cursor"</code> (emitted when the user initiates a cursor movement); <code>"populate-popup"</code> (emitted before showing the context menu of the entry; it can be used to add items to it).</p>
    <list>
      <item><p><code>get_buffer()</code> and <code>set_buffer(buffer)</code>, where <code>buffer</code> is a Gtk.EntryBuffer object, can be used to get and set the buffer for the entry.</p></item>
      <item><p><code>get_text()</code> and <code>set_text("some text")</code> can be used to get and set the content for the entry.</p></item>
      <item><p><code>get_text_length()</code> is self-explanatory.</p></item>
      <item><p><code>get_text_area()</code> gets the area where the entry's text is drawn.</p></item>
      <item><p>If we set <code>set_visibility(False)</code> the characters in the entry are displayed as the invisible char. This is the best available in the current font, but it can be changed with <code>set_invisible_char(ch)</code>, where <code>ch</code> is a Unicode charcater. The latter method is reversed by <code>unset_invisbile_char()</code>.</p></item>
      <item><p><code>set_max_length(int)</code>, where <code>int</code> is an integer, truncates every entry longer than <code>int</code> to have the desired maximum length.</p></item>
      <item><p>By default, if you press the Entry key the Gtk.Entry emits the signal <code>"activate"</code>. If you would like to activate the default widget for the window (set using <code>set_default(widget)</code> on the window), then use <code>set_activates_default(True)</code>.</p></item>
      <item><p>To set a frame around the entry: <code>set_has_frame(True)</code>.</p></item>
      <item><p><code>set_placeholder_text("some text")</code> sets the text to be displayed in the entry when it is empty and unfocused.</p></item>
      <item><p><code>set_overwrite_mode(True)</code> and <code>set_overwrite_mode(False)</code> are self-explanatory.</p></item>
      <item><p>If we have <code>set_editable(False)</code> the user cannot edit the text in the widget.</p></item>
      <item><p><code>set_completion(completion)</code>, where <code>completion</code> is a <link href="http://developer.gnome.org/gtk3/unstable/GtkEntryCompletion.html"><code>Gtk.EntryCompletion</code></link>, sets completion - or disables it if <code>completion</code> is <code>None</code>.</p></item>
      <item><p>An Entry widget can display progress or activity information behind the text. We use <code>set_progress_fraction(fraction)</code>, where <code>fraction</code> is a <code>float</code> between <code>0.0</code> and <code>1.0</code> inclusive, to fill in the given fraction of the bar. We use <code>set_progress_pulse_step()</code> to set the fraction of total entry width to move the progress bouncing block for each call to <code>progress_pulse()</code>. The latter method indicates that some progress is made, and causes the progress indicator of the entry to enter "activity mode", where a block bounces back and forth. Each call to <code>progress_pulse()</code> causes the block to move by a little bit (the amount of movement per pulse is determined, as said before, by <code>set_progress_pulse_step()</code>).</p></item>
      <item><p>An Entry widget can also show icons. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use <code>set_icon_from_stock(icon_position, stock_id)</code>, or one of <code>set_icon_from_pixbuf(icon_position, pixbuf)</code>, <code>set_icon_from_icon_name(icon_position, icon_name)</code>, where <code>icon_position</code> is one of <code>Gtk.EntryIconPosition.PRIMARY</code> (to set the icon at the beginning of the entry) <code>Gtk.EntryIconPosition.SECONDARY</code> (to set the icon at the end of the entry). To set a tooltip on an icon, use <code>set_icon_tooltip_text("tooltip text")</code> or <code>set_icon_tooltip_markup("tooltip text in Pango markup language")</code>.</p></item>
    </list>
  </section>

  <section id="references">
    <title>API References</title>
    <p>In this sample we used the following:</p>
    <list>
      <item><p><link href="http://developer.gnome.org/gtk3/unstable/GtkEntry.html">GtkEntry</link></p></item>
    </list>
  </section>
</page>
