<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Entry</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="index.html" title="Programming with gtkmm">
<link rel="up" href="chapter-misc-widgets.html" title="Chapter 6. Miscellaneous Widgets">
<link rel="prev" href="chapter-misc-widgets.html" title="Chapter 6. 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 6. 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="sect1" title="Entry">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-text-entry"></a>Entry</h2></div></div></div>
<div class="sect2" title="Simple Use">
<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> and <code class="literal">changed</code>, for just this
purpose. <code class="literal">activate</code> is emitted when the user presses the
enter 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.
</p>
<p><a class="ulink" href="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1Entry.html" target="_top">Reference</a></p>
<div class="sect3" title="Simple Entry Example">
<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 6.2. Entry</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/entry.png" alt="Entry"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/cgit/gtkmm-documentation/tree/examples/book/entry/simple" target="_top">Source Code</a></p>
<p>File: <code class="filename">examplewindow.h</code>
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H
#include <gtkmm.h>
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::HBox m_HBox;
Gtk::VBox m_VBox;
Gtk::Entry m_Entry;
Gtk::Button m_Button_Close;
Gtk::CheckButton m_CheckButton_Editable, m_CheckButton_Visible;
};
#endif //GTKMM_EXAMPLEWINDOW_H
</pre>
<p>File: <code class="filename">examplewindow.cc</code>
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include <iostream>
ExampleWindow::ExampleWindow()
: m_Button_Close("Close"),
m_CheckButton_Editable("Editable"),
m_CheckButton_Visible("Visible")
{
set_size_request(200, 100);
set_title("Gtk::Entry");
add(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_VBox.pack_start(m_Entry);
// Note that add() can also be used instead of pack_xxx()
m_VBox.add(m_HBox);
m_HBox.pack_start(m_CheckButton_Editable);
m_CheckButton_Editable.signal_toggled().connect( sigc::mem_fun(*this,
&ExampleWindow::on_checkbox_editable_toggled) );
m_CheckButton_Editable.set_active(true);
m_HBox.pack_start(m_CheckButton_Visible);
m_CheckButton_Visible.signal_toggled().connect( sigc::mem_fun(*this,
&ExampleWindow::on_checkbox_visibility_toggled) );
m_CheckButton_Visible.set_active(true);
m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_button_close) );
m_VBox.pack_start(m_Button_Close);
m_Button_Close.set_flags(Gtk::CAN_DEFAULT);
m_Button_Close.grab_default();
show_all_children();
}
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()
{
hide();
}
</pre>
<p>File: <code class="filename">main.cc</code>
</p>
<pre class="programlisting">
#include <gtkmm/main.h>
#include "examplewindow.h"
int main(int argc, char *argv[])
{
Gtk::Main kit(argc, argv);
ExampleWindow window;
//Shows the window and returns when it is closed.
Gtk::Main::run(window);
return 0;
}
</pre>
</div>
</div>
<div class="sect2" title="Entry Completion">
<div class="titlepage"><div><div><h3 class="title">
<a name="sec-text-entry-completion"></a>Entry Completion</h3></div></div></div>
<p>A <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 a
<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>. That callback
function. 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="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1EntryCompletion.html" target="_top">Reference</a></p>
<div class="sect3" title="Entry Completion Example">
<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 6.3. Entry Completion</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/entry_completion.png" alt="Entry Completion"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/cgit/gtkmm-documentation/tree/examples/book/entry/completion" target="_top">Source Code</a></p>
<p>File: <code class="filename">examplewindow.h</code>
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H
#include <gtkmm.h>
class ExampleWindow : public Gtk::Window
{
public:
ExampleWindow();
virtual ~ExampleWindow();
protected:
//Signal handlers:
void on_button_close();
void on_completion_action_activated(int index);
//See the comment in the implementation:
//bool on_completion_match(const Glib::ustring& key, const Gtk::TreeModel::const_iterator& 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<unsigned int> m_col_id;
Gtk::TreeModelColumn<Glib::ustring> m_col_name;
};
ModelColumns m_Columns;
typedef std::map<int, Glib::ustring> type_actions_map;
type_actions_map m_CompletionActions;
//Child widgets:
Gtk::HBox m_HBox;
Gtk::VBox m_VBox;
Gtk::Entry m_Entry;
Gtk::Label m_Label;
Gtk::Button m_Button_Close;
};
#endif //GTKMM_EXAMPLEWINDOW_H
</pre>
<p>File: <code class="filename">examplewindow.cc</code>
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include <iostream>
ExampleWindow::ExampleWindow() :
m_Label("Press a or b to see a list of possible completions and actions."),
m_Button_Close("Close")
{
//set_size_request(200, 100);
set_title("Gtk::EntryCompletion");
add(m_VBox);
m_VBox.pack_start(m_Entry, Gtk::PACK_SHRINK);
m_VBox.pack_start(m_Label, Gtk::PACK_EXPAND_WIDGET);
m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_button_close) );
m_VBox.pack_start(m_Button_Close, Gtk::PACK_SHRINK);
m_Button_Close.set_flags(Gtk::CAN_DEFAULT);
m_Button_Close.grab_default();
//Add an EntryCompletion:
Glib::RefPtr<Gtk::EntryCompletion> completion =
Gtk::EntryCompletion::create();
m_Entry.set_completion(completion);
//Create and fill the completion's filter model
Glib::RefPtr<Gtk::ListStore> refCompletionModel =
Gtk::ListStore::create(m_Columns);
completion->set_model(refCompletionModel);
// For more complex comparisons, use a filter match callback, like this.
// See the comment below for more details:
//completion->set_match_func( sigc::mem_fun(*this,
//&ExampleWindow::on_completion_match) );
//Fill the TreeView's model
Gtk::TreeModel::Row row = *(refCompletionModel->append());
row[m_Columns.m_col_id] = 1;
row[m_Columns.m_col_name] = "Alan Zebedee";
row = *(refCompletionModel->append());
row[m_Columns.m_col_id] = 2;
row[m_Columns.m_col_name] = "Adrian Boo";
row = *(refCompletionModel->append());
row[m_Columns.m_col_id] = 3;
row[m_Columns.m_col_name] = "Bob McRoberts";
row = *(refCompletionModel->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->set_text_column(m_Columns.m_col_name);
//Add actions to the completion:
//These are just extra items shown at the bottom of the list of possible
//completions.
//Remember them for later.
m_CompletionActions[0] = "Use Wizard";
m_CompletionActions[1] = "Browse for Filename";
for(type_actions_map::iterator iter = m_CompletionActions.begin();
iter != m_CompletionActions.end(); ++iter)
{
int position = iter->first;
Glib::ustring title = iter->second;
completion->insert_action_text(title, position);
}
completion->signal_action_activated().connect( sigc::mem_fun(*this,
&ExampleWindow::on_completion_action_activated) );
show_all_children();
}
ExampleWindow::~ExampleWindow()
{
}
void ExampleWindow::on_button_close()
{
hide();
}
/* 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& key, const
Gtk::TreeModel::const_iterator& iter)
{
if(iter)
{
Gtk::TreeModel::Row row = *iter;
Glib::ustring::size_type key_length = key.size();
Glib::ustring filter_string = row[m_Columns.m_col_name];
Glib::ustring 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.
}
*/
void ExampleWindow::on_completion_action_activated(int index)
{
type_actions_map::iterator iter = m_CompletionActions.find(index);
if(iter != m_CompletionActions.end()) //If it's in the map
{
Glib::ustring title = iter->second;
std::cout << "Action selected: " << title << std::endl;
}
}
</pre>
<p>File: <code class="filename">main.cc</code>
</p>
<pre class="programlisting">
#include <gtkmm/main.h>
#include "examplewindow.h"
int main(int argc, char *argv[])
{
Gtk::Main kit(argc, argv);
ExampleWindow window;
//Shows the window and returns when it is closed.
Gtk::Main::run(window);
return 0;
}
</pre>
</div>
</div>
<div class="sect2" title="Entry Icons">
<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 specifed by methods such as
<code class="methodname">set_icon_from_pixbuf()</code> or
<code class="methodname">set_icon_from_stock()</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="sect3" title="Entry Icon Example">
<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 stock
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 6.4. Entry with Icon</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/entry_icon.png" alt="Entry with Icon"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/cgit/gtkmm-documentation/tree/examples/book/entry/icon" target="_top">Source Code</a></p>
<p>File: <code class="filename">examplewindow.h</code>
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H
#include <gtkmm.h>
class ExampleWindow : public Gtk::Window
{
public:
ExampleWindow();
virtual ~ExampleWindow();
protected:
//Signal handlers:
void on_icon_pressed(Gtk::EntryIconPosition icon_pos, const GdkEventButton* event);
void on_button_close();
//Child widgets:
Gtk::VBox m_VBox;
Gtk::Entry m_Entry;
Gtk::Button m_Button_Close;
};
#endif //GTKMM_EXAMPLEWINDOW_H
</pre>
<p>File: <code class="filename">examplewindow.cc</code>
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include <iostream>
ExampleWindow::ExampleWindow()
: m_Button_Close("Close")
{
set_title("Gtk::Entry");
add(m_VBox);
m_Entry.set_max_length(50);
m_Entry.set_text("Hello world");
m_VBox.pack_start(m_Entry, Gtk::PACK_SHRINK);
m_Entry.set_icon_from_stock(Gtk::Stock::FIND);
m_Entry.signal_icon_press().connect( sigc::mem_fun(*this, &ExampleWindow::on_icon_pressed) );
m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_button_close) );
m_VBox.pack_start(m_Button_Close, Gtk::PACK_SHRINK);
m_Button_Close.set_flags(Gtk::CAN_DEFAULT);
m_Button_Close.grab_default();
show_all_children();
}
ExampleWindow::~ExampleWindow()
{
}
void ExampleWindow::on_icon_pressed(Gtk::EntryIconPosition /* icon_pos */, const GdkEventButton* /* event */)
{
std::cout << "Icon pressed." << std::endl;
}
void ExampleWindow::on_button_close()
{
hide();
}
</pre>
<p>File: <code class="filename">main.cc</code>
</p>
<pre class="programlisting">
#include <gtkmm/main.h>
#include "examplewindow.h"
int main(int argc, char *argv[])
{
Gtk::Main kit(argc, argv);
ExampleWindow window;
//Shows the window and returns when it is closed.
Gtk::Main::run(window);
return 0;
}
</pre>
</div>
</div>
<div class="sect2" title="Entry Progress">
<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="sect3" title="Entry Progress Example">
<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 6.5. Entry with Progress Bar</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/entry_progress.png" alt="Entry with Progress Bar"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/cgit/gtkmm-documentation/tree/examples/book/entry/progress" target="_top">Source Code</a></p>
<p>File: <code class="filename">examplewindow.h</code>
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H
#include <gtkmm.h>
class ExampleWindow : public Gtk::Window
{
public:
ExampleWindow();
virtual ~ExampleWindow();
protected:
//Signal handlers:
bool on_timeout();
void on_button_close();
//Child widgets:
Gtk::VBox m_VBox;
Gtk::Entry m_Entry;
Gtk::Button m_Button_Close;
};
#endif //GTKMM_EXAMPLEWINDOW_H
</pre>
<p>File: <code class="filename">examplewindow.cc</code>
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include <iostream>
ExampleWindow::ExampleWindow()
: m_Button_Close("Close")
{
set_title("Gtk::Entry");
add(m_VBox);
m_Entry.set_max_length(50);
m_Entry.set_text("Hello world");
m_VBox.pack_start(m_Entry, Gtk::PACK_SHRINK);
//Change the progress fraction every 0.1 second:
Glib::signal_timeout().connect(
sigc::mem_fun(*this, &ExampleWindow::on_timeout),
100
);
m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_button_close) );
m_VBox.pack_start(m_Button_Close, Gtk::PACK_SHRINK);
m_Button_Close.set_flags(Gtk::CAN_DEFAULT);
m_Button_Close.grab_default();
show_all_children();
}
ExampleWindow::~ExampleWindow()
{
}
bool ExampleWindow::on_timeout()
{
static double fraction = 0;
m_Entry.set_progress_fraction(fraction);
fraction += 0.01;
if(fraction > 1)
fraction = 0;
return true;
}
void ExampleWindow::on_button_close()
{
hide();
}
</pre>
<p>File: <code class="filename">main.cc</code>
</p>
<pre class="programlisting">
#include <gtkmm/main.h>
#include "examplewindow.h"
int main(int argc, char *argv[])
{
Gtk::Main kit(argc, argv);
ExampleWindow window;
//Shows the window and returns when it is closed.
Gtk::Main::run(window);
return 0;
}
</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 6. 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>
