Entry
| Chapter 7. Miscellaneous Widgets |

## Entry

### Simple Use

Entry widgets allow the user to enter text. You can change the contents with the `set_text()` method, and read the current contents with the `get_text()` method.

Occasionally you might want to make an `Entry` widget read-only. This can be done by passing `false` to the `set_editable()` method.

For the input of passwords, passphrases and other information you don't want echoed on the screen, calling `set_visibility()` with `false` will cause the text to be hidden.

You might want to be notified whenever the user types in a text entry widget. `Gtk::Entry` provides two signals, `activate` and `changed`, for this purpose. `activate` is emitted when the user presses the Enter key in a text-entry widget; `changed` 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 `focus_out_event` signal that `Gtk::Entry` inherits from `Gtk::Widget` can notify you when that happens. The ComboBox with an Entry section contains example programs that use these signals.

If you pass `true` to the `set_activates_default()` method, pressing Enter in the `Gtk::Entry` will activate the default widget for the window containing the `Gtk::Entry`. 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 `Gtk::Widget::set_can_default()` and `Gtk::Widget::grab_default()`.

Reference

#### Simple Entry Example

This example uses `Gtk::Entry`. It also has two `CheckButton`s, with which you can toggle the editable and visible flags.

Figure 7.2. Entry

Source Code

File: `examplewindow.h` (For use with gtkmm 3, not gtkmm 2)

    #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::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

File: `examplewindow.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <iostream>

    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");

      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_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();
    }

File: `main.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <gtkmm/application.h>

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

      ExampleWindow window;

      //Shows the window and returns when it is closed.
      return app->run(window);
    }

### Entry Completion

A `Entry` 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.

To enable this functionality, you must create a `EntryCompletion` object, and provide it to the `Entry` widget via the `set_completion()` method.

The `EntryCompletion` may use a `TreeModel` containing possible entries, specified with `set_model()`. You should then call `set_text_column()` to specify which of your model columns should be used to match possible text entries.

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 `set_match_func()`. This is also useful if you wish to match on a part of the string other than the start.

Reference

#### Entry Completion Example

This example creates a `Gtk::EntryCompletion` and associates it with a `Gtk::Entry` widget. The completion uses a `Gtk::TreeModel` of possible entries, and some additional actions.

Figure 7.3. Entry Completion

Source Code

File: `examplewindow.h` (For use with gtkmm 3, not gtkmm 2)

    #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::Box m_HBox;
      Gtk::Box m_VBox;
      Gtk::Entry m_Entry;
      Gtk::Label m_Label;
      Gtk::Button m_Button_Close;
    };

    #endif //GTKMM_EXAMPLEWINDOW_H

File: `examplewindow.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <iostream>

    ExampleWindow::ExampleWindow()
    : m_VBox(Gtk::ORIENTATION_VERTICAL),
      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_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;
      }
    }

File: `main.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <gtkmm/application.h>

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

      ExampleWindow window;

      //Shows the window and returns when it is closed.
      return app->run(window);
    }

### Entry Icons

An `Entry` widget can show an icon at the start or end of the text area. The icon can be specifed by methods such as `set_icon_from_pixbuf()` or `set_icon_from_stock()`. An application can respond to the user pressing the icon by handling the `signal_icon_press` signal.

#### Entry Icon Example

This example shows a `Gtk::Entry` widget with a stock search icon, and prints text to the terminal when the icon is pressed.

Figure 7.4. Entry with Icon

Source Code

File: `examplewindow.h` (For use with gtkmm 3, not gtkmm 2)

    #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::Box m_VBox;
      Gtk::Entry m_Entry;
      Gtk::Button m_Button_Close;
    };

    #endif //GTKMM_EXAMPLEWINDOW_H

File: `examplewindow.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <iostream>

    ExampleWindow::ExampleWindow()
    : m_VBox(Gtk::ORIENTATION_VERTICAL),
      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_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();
    }

File: `main.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <gtkmm/application.h>

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

      ExampleWindow window;

      //Shows the window and returns when it is closed.
      return app->run(window);
    }

### Entry Progress

An `Entry` widget can show a progress bar inside the text area, under the entered text. The progress bar will be shown if the `set_progress_fraction()` or `set_progress_pulse_step()` methods are called.

#### Entry Progress Example

This example shows a `Gtk::Entry` widget with a progress bar.

Figure 7.5. Entry with Progress Bar

Source Code

File: `examplewindow.h` (For use with gtkmm 3, not gtkmm 2)

    #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::Box m_VBox;
      Gtk::Entry m_Entry;
      Gtk::Button m_Button_Close;
    };

    #endif //GTKMM_EXAMPLEWINDOW_H

File: `examplewindow.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <iostream>

    ExampleWindow::ExampleWindow()
    : m_VBox(Gtk::ORIENTATION_VERTICAL),
      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_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();
    }

File: `main.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <gtkmm/application.h>

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

      ExampleWindow window;

      //Shows the window and returns when it is closed.
      return app->run(window);
    }

Chapter 7. Miscellaneous Widgets |  | SpinButton