libs/gtkmm2/gtk/src/entrycompletion.hg

   1 /* $Id: entrycompletion.hg,v 1.24 2006/07/19 16:58:50 murrayc Exp $ */
   2
   3 /* Copyright (C) 2003 The gtkmm Development Team
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the Free
  17  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19
  20 #include <gtkmm/widget.h>
  21 #include <gtkmm/treemodel.h>
  22
  23 _DEFS(gtkmm,gtk)
  24 _PINCLUDE(glibmm/private/object_p.h)
  25
  26
  27 namespace Gtk
  28 {
  29
  30 class Entry;
  31
  32 //TODO: This should derive+implement from CellLayout, when we can break ABI.
  33 //Then we should add "It derives from the Gtk::CellLayout, to allow the user to add extra cells to the Gtk::TreeView with completion matches".
  34
  35 /** Completion functionality for Gtk::Entry.
  36  *
  37  * Gtk::EntryCompletion is an auxiliary object to be used in conjunction with
  38  * Gtk::Entry to provide the completion functionality.
  39  *
  40  * "Completion functionality" means that when the user modifies the text in the
  41  * entry, Gtk::EntryCompletion checks which rows in the model match the current
  42  * content of the entry, and displays a list of matches. By default, the
  43  * matching is done by comparing the entry text case-insensitively against
  44  * the text column of the model (see set_text_column()),
  45  * but this can be overridden with a custom match function (see set_match_func()).
  46  *
  47  * When the user selects a completion, the content of the entry is updated.
  48  * By default, the content of the entry is replaced by the text column of the
  49  * model, but this can be overridden by connecting to the match_selected signal
  50  * and updating the entry in the signal handler. Note that you should return true
  51  * from the signal handler to suppress the default behaviour.
  52  *
  53  * To add completion functionality to an entry, use Gtk::Entry::set_completion().
  54  *
  55  * In addition to regular completion matches, which will be inserted into
  56  * the entry when they are selected, Gtk::EntryCompletion also allows the display of
  57  * "actions" in the popup window. Their appearance is similar to menu items,
  58  * to differentiate them clearly from completion strings. When an action is
  59  * selected, the action_activated signal is emitted.
  60  */
  61 class EntryCompletion : public Glib::Object
  62 {
  63   _CLASS_GOBJECT(EntryCompletion, GtkEntryCompletion, GTK_ENTRY_COMPLETION, Glib::Object, GObject)
  64
  65 protected:
  66   _CTOR_DEFAULT()
  67
  68 public:
  69   _WRAP_CREATE()
  70
  71   //Careful, this actually returns a GtkWidget*, so it might not always be a GtkEntry in future GTK+ versions.
  72   _WRAP_METHOD(Entry* get_entry(), gtk_entry_completion_get_entry)
  73   _WRAP_METHOD(const Entry* get_entry() const, gtk_entry_completion_get_entry)
  74
  75   _WRAP_METHOD(void set_model(const Glib::RefPtr<TreeModel>& model), gtk_entry_completion_set_model)
  76   _WRAP_METHOD(Glib::RefPtr<TreeModel> get_model(), gtk_entry_completion_get_model, refreturn)
  77   _WRAP_METHOD(Glib::RefPtr<const TreeModel> get_model() const, gtk_entry_completion_get_model, refreturn, constversion)
  78
  79   /// For example, bool on_match(const Glib::ustring& key, const TreeModel::const_iterator& iter);
  80   typedef sigc::slot<bool, const Glib::ustring&, const TreeModel::const_iterator&> SlotMatch;
  81
  82   void set_match_func(const SlotMatch& slot);
  83   _IGNORE(gtk_entry_completion_set_match_func)
  84
  85   _WRAP_METHOD(void set_minimum_key_length(int length), gtk_entry_completion_set_minimum_key_length)
  86   _WRAP_METHOD(int get_minimum_key_length() const, gtk_entry_completion_get_minimum_key_length)
  87   _WRAP_METHOD(void complete(), gtk_entry_completion_complete)
  88
  89   _WRAP_METHOD(void insert_prefix(), gtk_entry_completion_insert_prefix)
  90
  91   //We reordered the parameters, compared to the C version, so that we can have method overloads without the index.
  92
  93   // TODO: We would really like an insert() which before-inserts an iterator, like ListStore::insert(),
  94   // but there is no EntryCompletion::insert_before() for us to use.
  95   void insert_action_text(const Glib::ustring& text, int index);
  96   void prepend_action_text(const Glib::ustring& text);
  97   //TODO: Add append_action_text() somehow? It would be slow if we count the children each time. murrayc.
  98   _IGNORE(gtk_entry_completion_insert_action_text)
  99   void insert_action_markup(const Glib::ustring& markup, int index);
 100   void prepend_action_markup(const Glib::ustring& markup);
 101   _IGNORE(gtk_entry_completion_insert_action_markup)
 102
 103   //TODO: Change default - it would be nicer to delete the last action instead of the first.
 104   _WRAP_METHOD(void delete_action(int index = 0), gtk_entry_completion_delete_action)
 105
 106   _WRAP_METHOD(void set_inline_completion(bool inline_completion = true), gtk_entry_completion_set_inline_completion)
 107   _WRAP_METHOD(bool get_inline_completion() const, gtk_entry_completion_get_inline_completion)
 108   _WRAP_METHOD(void set_inline_selection(bool inline_selection = true), gtk_entry_completion_set_inline_selection)
 109   _WRAP_METHOD(bool get_inline_selection() const, gtk_entry_completion_get_inline_selection)
 110   _WRAP_METHOD(void set_popup_completion(bool popup_completion = true), gtk_entry_completion_set_popup_completion)
 111   _WRAP_METHOD(bool get_popup_completion() const, gtk_entry_completion_get_popup_completion)
 112
 113   _WRAP_METHOD(void set_popup_set_width(bool popup_set_width = true), gtk_entry_completion_set_popup_set_width)
 114   _WRAP_METHOD(bool get_popup_set_width() const, gtk_entry_completion_get_popup_set_width)
 115
 116   //TODO This is wrongly named: Deprecate it and add set_popup_single_match().
 117   _WRAP_METHOD(void set_popup_single_width(bool popup_single_match = true), gtk_entry_completion_set_popup_single_match)
 118
 119   _WRAP_METHOD(bool get_popup_single_match() const, gtk_entry_completion_get_popup_single_match)
 120   _WRAP_METHOD(Glib::ustring get_completion_prefix() const, gtk_entry_completion_get_completion_prefix)
 121
 122   _WRAP_METHOD(void set_text_column(const TreeModelColumnBase& column), gtk_entry_completion_set_text_column)
 123   _WRAP_METHOD(void set_text_column(int column), gtk_entry_completion_set_text_column)
 124   _WRAP_METHOD(int get_text_column(), gtk_entry_completion_get_text_column)
 125
 126   /** Emitted when an action is activated.
 127    *
 128    * @param index The index of the activated action.
 129    */
 130   _WRAP_SIGNAL(void action_activated(int index), action_activated)
 131
 132   //We completely hand-code these signals because we want to change how the parameters are wrapped,
 133   //because we need both the iter and the model to make the C++ iter.
 134   _IGNORE_SIGNAL(match_selected)
 135   _IGNORE_SIGNAL(cursor_on_match)
 136
 137   /** Emitted when a match from the list is selected.
 138    * The default behaviour is to replace the contents of the
 139    * entry with the contents of the text column in the row
 140    * pointed to by @a iter.
 141    *
 142    * @param model The TreeModel containing the matches
 143    * @param iter A TreeModel::iterator positioned at the selected match
 144    * @result true if the signal has been handled
 145    *
 146    * @par Prototype:
 147    * <tt>bool %on_match_selected(const TreeModel::iterator& iter)</tt>
 148    */
 149   Glib::SignalProxy1< bool, const TreeModel::iterator& > signal_match_selected();
 150
 151   /** Emitted when a match from the cursor is on a match
 152    * of the list. The default behaviour is to replace the contents
 153    * of the entry with the contents of the text column in the row
 154    * pointed to by @a iter.
 155    *
 156    * @param model The TreeModel containing the matches
 157    * @param iter A TreeModel::iterator positioned at the selected match
 158    * @result true if the signal has been handled
 159    *
 160    * @par Prototype:
 161    * <tt>bool %on_cursor_on_match(const TreeModel::iterator& iter)</tt>
 162    *
 163    * @newin2p12
 164    */
 165   Glib::SignalProxy1< bool, const TreeModel::iterator& > signal_cursor_on_match();
 166
 167
 168   #m4begin
 169 dnl// Hook in custom callback.
 170 dnl// It will use the callback.
 171 dnl
 172   _PUSH(SECTION_PCC_CLASS_INIT_DEFAULT_SIGNAL_HANDLERS)
 173     klass->match_selected = &match_selected_callback_custom;
 174   _SECTION(SECTION_PH_DEFAULT_SIGNAL_HANDLERS)
 175     static gboolean match_selected_callback_custom(GtkEntryCompletion* self, GtkTreeModel* c_model, GtkTreeIter* c_iter);
 176   _POP()
 177 #m4end
 178
 179   //We use no_default_handler for these signals, because we can not add a new vfunc without breaking ABI.
 180   //TODO: Remove no_default_handler when we do an ABI-break-with-parallel-install.
 181
 182   /** Emitted when the inline autocompletion is triggered.
 183    * The default behaviour is to make the entry display the
 184    * whole prefix and select the newly inserted part.
 185    *
 186    * Applications may connect to this signal in order to insert only a
 187    * smaller part of the @a prefix into the entry - e.g. the entry used in
 188    * the FileChooser inserts only the part of the prefix up to the
 189    * next '/'.
 190    *
 191    * @newin2p6
 192    *
 193    * @param prefix The common prefix of all possible completions.
 194    * @result true if the signal has been handled
 195    */
 196   _WRAP_SIGNAL(bool insert_prefix(const Glib::ustring& prefix), insert_prefix, no_default_handler)
 197
 198   _WRAP_PROPERTY("model", Glib::RefPtr<Gtk::TreeModel>)
 199   _WRAP_PROPERTY("minimum_key_length", int)
 200   _WRAP_PROPERTY("text_column, int)
 201   _WRAP_PROPERTY("inline_completion", bool)
 202   _WRAP_PROPERTY("popup_completion", bool)
 203   _WRAP_PROPERTY("popup_set_width", bool)
 204   _WRAP_PROPERTY("popup_single_match", bool)
 205   _WRAP_PROPERTY("inline-selection", bool)
 206
 207 protected:
 208
 209 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 210   //Default Signal Handler:
 211   virtual bool on_match_selected(const TreeModel::iterator& iter);
 212   //No default handler for on_cursor_on_match(), to preserver ABI. TODO: Add this when we can break ABI.
 213 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 214 };
 215
 216 } // namespace Gtk
 217