File: sec-text-entry.html

package info (click to toggle)
gtkmm-documentation 4.12.0-1
links: PTS, VCS
area: main
in suites: forky, trixie
size: 25,772 kB
sloc: cpp: 15,541; javascript: 1,208; makefile: 1,080; python: 401; xml: 106; perl: 67; sh: 8
file content (694 lines) | stat: -rw-r--r-- 22,496 bytes
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="highlight.min.css">
<script src="highlight.min.js"></script><script>
      hljs.configure({languages: ['cpp']});
      hljs.highlightAll();
    </script><title>Entry</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Programming with gtkmm 4">
<link rel="up" href="chapter-misc-widgets.html" title="Chapter 8. Miscellaneous Widgets">
<link rel="prev" href="chapter-misc-widgets.html" title="Chapter 8. Miscellaneous Widgets">
<link rel="next" href="sec-spinbutton.html" title="SpinButton">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Entry</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="chapter-misc-widgets.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center">Chapter 8. Miscellaneous Widgets</th>
<td width="20%" align="right"> <a accesskey="n" href="sec-spinbutton.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-text-entry"></a>Entry</h2></div></div></div>


<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="sec-text-entry-simple"></a>Simple Use</h3></div></div></div>


<p>
Entry widgets allow the user to enter text. You can change the contents with the <code class="methodname">set_text()</code> method,
and read the current contents with the <code class="methodname">get_text()</code> method.
</p>

<p>
Occasionally you might want to make an <code class="classname">Entry</code> widget
read-only. This can be done by passing <code class="literal">false</code> to the
<code class="methodname">set_editable()</code> method.
</p>

<p>
For the input of passwords, passphrases and other information you don't want
echoed on the screen, calling <code class="methodname">set_visibility()</code> with
<code class="literal">false</code> will cause the text to be hidden.
</p>

<p>
You might want to be notified whenever the user types in a text entry widget.
<code class="classname">Gtk::Entry</code> provides two signals,
<code class="literal">activate</code> (since <span class="application">gtkmm</span> 4.8) and <code class="literal">changed</code>, for this purpose.
<code class="literal">activate</code> is emitted when the user presses the <span class="keycap"><strong>Enter</strong></span> key in
a text-entry widget; <code class="literal">changed</code> is emitted when the text in
the widget changes. You can use these, for instance, to validate or filter
the text the user types. Moving the keyboard focus to another widget may also
signal that the user has finished entering text. The <code class="literal">leave</code>
signal in a <code class="classname">Gtk::EventControllerFocus</code> can notify you when
that happens. The <a class="link" href="sec-comboboxentry.html" title="ComboBox with an Entry">ComboBox with an Entry</a>
section contains example programs that use these signals.
</p>

<p>
If you pass <code class="literal">true</code> to the <code class="methodname">set_activates_default()</code>
method, pressing <span class="keycap"><strong>Enter</strong></span> in the <code class="classname">Gtk::Entry</code> will activate
the default widget for the window containing the <code class="classname">Gtk::Entry</code>.
This is especially useful in dialog boxes. The default widget is usually one of
the dialog buttons, which e.g. will close the dialog box. To set a widget as the
default widget, use <code class="methodname">Gtk::Window::set_default_widget()</code>.
</p>

<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1Entry.html" target="_top">Reference</a></p>

<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="entry-example"></a>Simple Entry Example</h4></div></div></div>

<p>
This example uses <code class="classname">Gtk::Entry</code>. It also has two
<code class="classname">CheckButton</code>s, with which you can toggle the editable and
visible flags.
</p>

<div class="figure">
<a name="figure-entry-simple"></a><p class="title"><b>Figure 8.2. Entry</b></p>
<div class="figure-contents">
  
  <div class="screenshot">
    <div class="mediaobject"><img src="figures/entry.png" alt="Entry"></div>
  </div>
</div>
</div>
<br class="figure-break">

<p><a class="ulink" href="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/entry/simple" target="_top">Source Code</a></p>

<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include &lt;gtkmm.h&gt;

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_checkbox_editable_toggled();
  void on_checkbox_visibility_toggled();
  void on_button_close();

  //Child widgets:
  Gtk::Box m_HBox;
  Gtk::Box m_VBox;
  Gtk::Entry m_Entry;
  Gtk::Button m_Button_Close;
  Gtk::CheckButton m_CheckButton_Editable, m_CheckButton_Visible;
};

#endif //GTKMM_EXAMPLEWINDOW_H
</code></pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;iostream&gt;

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::Orientation::VERTICAL),
  m_Button_Close("Close"),
  m_CheckButton_Editable("Editable"),
  m_CheckButton_Visible("Visible")
{
  set_size_request(200, 100);
  set_title("Gtk::Entry");

  set_child(m_VBox);

  m_Entry.set_max_length(50);
  m_Entry.set_text("hello");
  m_Entry.set_text(m_Entry.get_text() + " world");
  m_Entry.select_region(0, m_Entry.get_text_length());
  m_Entry.set_expand(true);
  m_VBox.append(m_Entry);

  m_VBox.append(m_HBox);

  m_HBox.append(m_CheckButton_Editable);
  m_CheckButton_Editable.set_expand(true);
  m_CheckButton_Editable.signal_toggled().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_checkbox_editable_toggled) );
  m_CheckButton_Editable.set_active(true);

  m_HBox.append(m_CheckButton_Visible);
  m_CheckButton_Visible.set_expand(true);
  m_CheckButton_Visible.signal_toggled().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_checkbox_visibility_toggled) );
  m_CheckButton_Visible.set_active(true);

  m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_button_close) );
  m_VBox.append(m_Button_Close);
  m_Button_Close.set_expand();
  set_default_widget(m_Button_Close);
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_checkbox_editable_toggled()
{
  m_Entry.set_editable(m_CheckButton_Editable.get_active());
}

void ExampleWindow::on_checkbox_visibility_toggled()
{
  m_Entry.set_visibility(m_CheckButton_Visible.get_active());
}

void ExampleWindow::on_button_close()
{
  set_visible(false);
}

</code></pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;gtkmm/application.h&gt;

int main(int argc, char *argv[])
{
  auto app = Gtk::Application::create("org.gtkmm.example");

  //Shows the window and returns when it is closed.
  return app-&gt;make_window_and_run&lt;ExampleWindow&gt;(argc, argv);
}
</code></pre>


</div>

</div>

<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="sec-text-entry-completion"></a>Entry Completion</h3></div></div></div>


<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="icons/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p><code class="classname">Gtk::EntryCompletion</code> is deprecated since <span class="application">gtkmm</span> 4.10.
There is no replacement in <span class="application">gtkmm</span>.
</p></td></tr>
</table></div>

<p>An <code class="classname">Entry</code> widget can offer a drop-down list of
pre-existing choices based on the first few characters typed by the user. For
instance, a search dialog could suggest text from previous searches.
</p>

<p>To enable this functionality, you must create an
<code class="classname">EntryCompletion</code> object, and provide it to the
<code class="classname">Entry</code> widget via the
<code class="methodname">set_completion()</code> method.</p>

<p>The <code class="classname">EntryCompletion</code> may use a
<code class="classname">TreeModel</code> containing possible entries, specified with
<code class="methodname">set_model()</code>. You should then call
<code class="methodname">set_text_column()</code> to specify which of your model columns
should be used to match possible text entries.</p>

<p>Alternatively, if a complete list of possible entries
would be too large or too inconvenient to generate, a callback slot may instead
be specified with <code class="methodname">set_match_func()</code>.
This is also useful if you wish to match on a part of the string other
than the start.</p>

<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1EntryCompletion.html" target="_top">Reference</a></p>

<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="entry-completion-example"></a>Entry Completion Example</h4></div></div></div>

<p>
This example creates a <code class="classname">Gtk::EntryCompletion</code> and associates
it with a <code class="classname">Gtk::Entry</code> widget. The completion uses a
<code class="classname">Gtk::TreeModel</code> of possible entries, and some additional
actions.
</p>

<div class="figure">
<a name="figure-entry-completion"></a><p class="title"><b>Figure 8.3. Entry Completion</b></p>
<div class="figure-contents">
  
  <div class="screenshot">
    <div class="mediaobject"><img src="figures/entry_completion.png" alt="Entry Completion"></div>
  </div>
</div>
</div>
<br class="figure-break">

<p><a class="ulink" href="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/entry/completion" target="_top">Source Code</a></p>

<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include &lt;gtkmm.h&gt;

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_button_close();

  //See the comment in the implementation:
  //bool on_completion_match(const Glib::ustring&amp; key, const Gtk::TreeModel::const_iterator&amp; iter);

  //Tree model columns, for the EntryCompletion's filter model:
  class ModelColumns : public Gtk::TreeModel::ColumnRecord
  {
  public:
    ModelColumns()
    { add(m_col_id); add(m_col_name); }

    Gtk::TreeModelColumn&lt;unsigned int&gt; m_col_id;
    Gtk::TreeModelColumn&lt;Glib::ustring&gt; m_col_name;
  };

  ModelColumns m_Columns;

  //Child widgets:
  Gtk::Box m_HBox;
  Gtk::Box m_VBox;
  Gtk::Entry m_Entry;
  Gtk::Label m_Label;
  Gtk::Button m_Button_Close;
};

#endif //GTKMM_EXAMPLEWINDOW_H
</code></pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;iostream&gt;

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::Orientation::VERTICAL),
  m_Label("Press a or b to see a list of possible completions."),
  m_Button_Close("Close")
{
  //set_size_request(200, 100);
  set_title("Gtk::EntryCompletion");

  set_child(m_VBox);
  m_VBox.append(m_Entry);

  m_VBox.append(m_Label);
  m_Label.set_expand(true);

  m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_button_close) );
  m_VBox.append(m_Button_Close);
  set_default_widget(m_Button_Close);

  //Add an EntryCompletion:
  auto completion =
      Gtk::EntryCompletion::create();
  m_Entry.set_completion(completion);

  //Create and fill the completion's filter model
  auto refCompletionModel =
      Gtk::ListStore::create(m_Columns);
  completion-&gt;set_model(refCompletionModel);

  // For more complex comparisons, use a filter match callback, like this.
  // See the comment below for more details:
  //completion-&gt;set_match_func( sigc::mem_fun(*this,
              //&amp;ExampleWindow::on_completion_match) );

  //Fill the TreeView's model
  auto row = *(refCompletionModel-&gt;append());
  row[m_Columns.m_col_id] = 1;
  row[m_Columns.m_col_name] = "Alan Zebedee";

  row = *(refCompletionModel-&gt;append());
  row[m_Columns.m_col_id] = 2;
  row[m_Columns.m_col_name] = "Adrian Boo";

  row = *(refCompletionModel-&gt;append());
  row[m_Columns.m_col_id] = 3;
  row[m_Columns.m_col_name] = "Bob McRoberts";

  row = *(refCompletionModel-&gt;append());
  row[m_Columns.m_col_id] = 4;
  row[m_Columns.m_col_name] = "Bob McBob";

  //Tell the completion what model column to use to
  //- look for a match (when we use the default matching, instead of
  //  set_match_func().
  //- display text in the entry when a match is found.
  completion-&gt;set_text_column(m_Columns.m_col_name);
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_close()
{
  set_visible(false);
}

/* You can do more complex matching with a handler like this.
 * For instance, you could check for substrings inside the string instead of the start,
 * or you could look for the key in extra model columns as well as the model column that will be displayed.
 * The code here is not actually more complex - it's a reimplementation of the default behaviour.
 *
bool ExampleWindow::on_completion_match(const Glib::ustring&amp; key, const
        Gtk::TreeModel::const_iterator&amp; iter)
{
  if(iter)
  {
    const auto row = *iter;

    const auto key_length = key.size();
    auto filter_string = row[m_Columns.m_col_name];

    auto filter_string_start = filter_string.substr(0, key_length);
    //The key is lower-case, even if the user input is not.
    filter_string_start = filter_string_start.lowercase();

    if(key == filter_string_start)
      return true; //A match was found.
  }

  return false; //No match.
}
*/
</code></pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;gtkmm/application.h&gt;

int main(int argc, char *argv[])
{
  auto app = Gtk::Application::create("org.gtkmm.example");

  //Shows the window and returns when it is closed.
  return app-&gt;make_window_and_run&lt;ExampleWindow&gt;(argc, argv);
}
</code></pre>


</div>
</div>

<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="sec-text-entry-icons"></a>Entry Icons</h3></div></div></div>


<p>An <code class="classname">Entry</code> widget can show an icon at the start or
end of the text area. The icon can be specified by methods such as
<code class="methodname">set_icon_from_paintable()</code> or
<code class="methodname">set_icon_from_icon_name()</code>. An application can respond to the
user pressing the icon by handling the
<code class="methodname">signal_icon_press</code> signal.</p>

<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="entry-icon-example"></a>Entry Icon Example</h4></div></div></div>

<p>
This example shows a <code class="classname">Gtk::Entry</code> widget with a named
search icon, and prints text to the terminal when the icon is pressed.
</p>

<div class="figure">
<a name="figure-entry-icon"></a><p class="title"><b>Figure 8.4. Entry with Icon</b></p>
<div class="figure-contents">
  
  <div class="screenshot">
    <div class="mediaobject"><img src="figures/entry_icon.png" alt="Entry with Icon"></div>
  </div>
</div>
</div>
<br class="figure-break">

<p><a class="ulink" href="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/entry/icon" target="_top">Source Code</a></p>

<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include &lt;gtkmm.h&gt;

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_icon_pressed(Gtk::Entry::IconPosition icon_pos);
  void on_button_close();

  //Child widgets:
  Gtk::Box m_VBox;
  Gtk::Entry m_Entry;
  Gtk::Button m_Button_Close;
};

#endif //GTKMM_EXAMPLEWINDOW_H
</code></pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;iostream&gt;

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::Orientation::VERTICAL),
  m_Button_Close("Close")
{
  set_title("Gtk::Entry");

  set_child(m_VBox);

  m_Entry.set_max_length(50);
  m_Entry.set_text("Hello world");
  m_VBox.append(m_Entry);

  m_Entry.set_icon_from_icon_name("edit-find");
  m_Entry.signal_icon_press().connect( sigc::mem_fun(*this, &amp;ExampleWindow::on_icon_pressed) );


  m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_button_close) );
  m_VBox.append(m_Button_Close);
  set_default_widget(m_Button_Close);
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_icon_pressed(Gtk::Entry::IconPosition /* icon_pos */)
{
  std::cout &lt;&lt; "Icon pressed." &lt;&lt; std::endl;
}

void ExampleWindow::on_button_close()
{
  set_visible(false);
}

</code></pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;gtkmm/application.h&gt;

int main(int argc, char *argv[])
{
  auto app = Gtk::Application::create("org.gtkmm.example");

  //Shows the window and returns when it is closed.
  return app-&gt;make_window_and_run&lt;ExampleWindow&gt;(argc, argv);
}
</code></pre>


</div>
</div>

<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="sec-text-entry-progress"></a>Entry Progress</h3></div></div></div>


<p>An <code class="classname">Entry</code> widget can show a progress bar inside the
text area, under the entered text. The progress bar will be shown if the
<code class="methodname">set_progress_fraction()</code> or
<code class="methodname">set_progress_pulse_step()</code> methods are called.</p>

<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="entry-progress-example"></a>Entry Progress Example</h4></div></div></div>

<p>
This example shows a <code class="classname">Gtk::Entry</code> widget with a progress
bar.
</p>

<div class="figure">
<a name="figure-entry-progress"></a><p class="title"><b>Figure 8.5. Entry with Progress Bar</b></p>
<div class="figure-contents">
  
  <div class="screenshot">
    <div class="mediaobject"><img src="figures/entry_progress.png" alt="Entry with Progress Bar"></div>
  </div>
</div>
</div>
<br class="figure-break">

<p><a class="ulink" href="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/entry/progress" target="_top">Source Code</a></p>

<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include &lt;gtkmm.h&gt;

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  bool on_timeout();
  void on_button_close();

  //Child widgets:
  Gtk::Box m_VBox;
  Gtk::Entry m_Entry;
  Gtk::Button m_Button_Close;
};

#endif //GTKMM_EXAMPLEWINDOW_H
</code></pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;iostream&gt;

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::Orientation::VERTICAL),
  m_Button_Close("Close")
{
  set_title("Gtk::Entry");

  set_child(m_VBox);

  m_Entry.set_max_length(50);
  m_Entry.set_text("Hello world");
  m_VBox.append(m_Entry);

  //Change the progress fraction every 0.1 second:
  Glib::signal_timeout().connect(
    sigc::mem_fun(*this, &amp;ExampleWindow::on_timeout),
    100
  );

  m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_button_close) );
  m_VBox.append(m_Button_Close);
  set_default_widget(m_Button_Close);
}

ExampleWindow::~ExampleWindow()
{
}

bool ExampleWindow::on_timeout()
{
  static double fraction = 0;
  m_Entry.set_progress_fraction(fraction);

  fraction += 0.01;
  if(fraction &gt; 1)
    fraction = 0;

  return true;
}

void ExampleWindow::on_button_close()
{
  set_visible(false);
}

</code></pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;gtkmm/application.h&gt;

int main(int argc, char *argv[])
{
  auto app = Gtk::Application::create("org.gtkmm.example");

  //Shows the window and returns when it is closed.
  return app-&gt;make_window_and_run&lt;ExampleWindow&gt;(argc, argv);
}
</code></pre>


</div>
</div>

</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="chapter-misc-widgets.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"><a accesskey="u" href="chapter-misc-widgets.html"><img src="icons/up.png" alt="Up"></a></td>
<td width="40%" align="right"> <a accesskey="n" href="sec-spinbutton.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 8. Miscellaneous Widgets </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> SpinButton</td>
</tr>
</table>
</div>
</body>
</html>