1
/* $Id: entrycompletion.hg,v 1.24 2006/07/19 16:58:50 murrayc Exp $ */
3
/* Copyright (C) 2003 The gtkmm Development Team
5
* This library is free software; you can redistribute it and/or
6
* modify it under the terms of the GNU Lesser General Public
7
* License as published by the Free Software Foundation; either
8
* version 2.1 of the License, or (at your option) any later version.
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
* Lesser General Public License for more details.
15
* You should have received a copy of the GNU Lesser 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.
20
#include <gtkmm/widget.h>
21
#include <gtkmm/celllayout.h>
22
#include <gtkmm/treemodel.h>
25
_PINCLUDE(glibmm/private/object_p.h)
33
//TODO: we should add "It derives from the Gtk::CellLayout, to allow the user to add extra cells to the Gtk::TreeView with completion matches".
35
/** Completion functionality for Gtk::Entry.
37
* Gtk::EntryCompletion is an auxiliary object to be used in conjunction with
38
* Gtk::Entry to provide the completion functionality.
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()).
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.
53
* To add completion functionality to an entry, use Gtk::Entry::set_completion().
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.
62
: public Glib::Object,
63
public Gtk::CellLayout,
66
_CLASS_GOBJECT(EntryCompletion, GtkEntryCompletion, GTK_ENTRY_COMPLETION, Glib::Object, GObject)
67
_IMPLEMENTS_INTERFACE(CellLayout)
68
_IMPLEMENTS_INTERFACE(Buildable)
76
//Careful, this actually returns a GtkWidget*, so it might not always be a GtkEntry in future GTK+ versions.
77
_WRAP_METHOD(Entry* get_entry(), gtk_entry_completion_get_entry)
78
_WRAP_METHOD(const Entry* get_entry() const, gtk_entry_completion_get_entry)
80
_WRAP_METHOD(void set_model(const Glib::RefPtr<TreeModel>& model), gtk_entry_completion_set_model)
81
_WRAP_METHOD(Glib::RefPtr<TreeModel> get_model(), gtk_entry_completion_get_model, refreturn)
82
_WRAP_METHOD(Glib::RefPtr<const TreeModel> get_model() const, gtk_entry_completion_get_model, refreturn, constversion)
84
/** Remove the model from the EntryCompletion.
92
/// For example, bool on_match(const Glib::ustring& key, const TreeModel::const_iterator& iter);
93
typedef sigc::slot<bool, const Glib::ustring&, const TreeModel::const_iterator&> SlotMatch;
95
void set_match_func(const SlotMatch& slot);
96
_IGNORE(gtk_entry_completion_set_match_func)
98
_WRAP_METHOD(void set_minimum_key_length(int length), gtk_entry_completion_set_minimum_key_length)
99
_WRAP_METHOD(int get_minimum_key_length() const, gtk_entry_completion_get_minimum_key_length)
100
_WRAP_METHOD(void complete(), gtk_entry_completion_complete)
102
_WRAP_METHOD(void insert_prefix(), gtk_entry_completion_insert_prefix)
104
//We reordered the parameters, compared to the C version, so that we can have method overloads without the index.
106
// TODO: We would really like an insert() which before-inserts an iterator, like ListStore::insert(),
107
// but there is no EntryCompletion::insert_before() for us to use.
108
void insert_action_text(const Glib::ustring& text, int index);
109
void prepend_action_text(const Glib::ustring& text);
110
//TODO: Add append_action_text() somehow? It would be slow if we count the children each time. murrayc.
111
_IGNORE(gtk_entry_completion_insert_action_text)
112
void insert_action_markup(const Glib::ustring& markup, int index);
113
void prepend_action_markup(const Glib::ustring& markup);
114
_IGNORE(gtk_entry_completion_insert_action_markup)
116
//TODO: Change default - it would be nicer to delete the last action instead of the first.
117
_WRAP_METHOD(void delete_action(int index = 0), gtk_entry_completion_delete_action)
119
_WRAP_METHOD(void set_inline_completion(bool inline_completion = true), gtk_entry_completion_set_inline_completion)
120
_WRAP_METHOD(bool get_inline_completion() const, gtk_entry_completion_get_inline_completion)
121
_WRAP_METHOD(void set_inline_selection(bool inline_selection = true), gtk_entry_completion_set_inline_selection)
122
_WRAP_METHOD(bool get_inline_selection() const, gtk_entry_completion_get_inline_selection)
123
_WRAP_METHOD(void set_popup_completion(bool popup_completion = true), gtk_entry_completion_set_popup_completion)
124
_WRAP_METHOD(bool get_popup_completion() const, gtk_entry_completion_get_popup_completion)
126
_WRAP_METHOD(void set_popup_set_width(bool popup_set_width = true), gtk_entry_completion_set_popup_set_width)
127
_WRAP_METHOD(bool get_popup_set_width() const, gtk_entry_completion_get_popup_set_width)
129
_WRAP_METHOD(void set_popup_single_match(bool popup_single_match = true), gtk_entry_completion_set_popup_single_match)
131
_WRAP_METHOD(bool get_popup_single_match() const, gtk_entry_completion_get_popup_single_match)
132
_WRAP_METHOD(Glib::ustring get_completion_prefix() const, gtk_entry_completion_get_completion_prefix)
134
_WRAP_METHOD(void set_text_column(const TreeModelColumnBase& column), gtk_entry_completion_set_text_column)
135
_WRAP_METHOD(void set_text_column(int column), gtk_entry_completion_set_text_column)
136
_WRAP_METHOD(int get_text_column() const, gtk_entry_completion_get_text_column)
138
/** Emitted when an action is activated.
140
* @param index The index of the activated action.
142
_WRAP_SIGNAL(void action_activated(int index), action_activated)
144
//We completely hand-code these signals because we want to change how the parameters are wrapped,
145
//because we need both the iter and the model to make the C++ iter.
146
_IGNORE_SIGNAL(match_selected)
147
_IGNORE_SIGNAL(cursor_on_match)
149
/** Emitted when a match from the list is selected.
150
* The default behaviour is to replace the contents of the
151
* entry with the contents of the text column in the row
152
* pointed to by @a iter.
154
* It is necessary to connect your signal handler <i>before</i>
155
* the default one, which would otherwise return <tt>true</tt>,
156
* a value which signifies that the signal has been handled,
157
* thus preventing any other handler from being invoked.
159
* To do this, pass <tt>false</tt> to this signal proxy's
160
* <tt>connect()</tt> method. For example:
161
* <tt> completion->signal_match_selected().connect(sigc::mem_fun(*this, &YourClass::on_completion_match_selected), false); </tt>
163
* @param model The TreeModel containing the matches
164
* @param iter A TreeModel::iterator positioned at the selected match
165
* @result true if the signal has been handled
168
* <tt>bool %on_match_selected(const TreeModel::iterator& iter)</tt>
170
Glib::SignalProxy1< bool, const TreeModel::iterator& > signal_match_selected();
172
/** Emitted when a match from the cursor is on a match
173
* of the list. The default behaviour is to replace the contents
174
* of the entry with the contents of the text column in the row
175
* pointed to by @a iter.
177
* @param model The TreeModel containing the matches
178
* @param iter A TreeModel::iterator positioned at the selected match
179
* @result true if the signal has been handled
182
* <tt>bool %on_cursor_on_match(const TreeModel::iterator& iter)</tt>
186
Glib::SignalProxy1< bool, const TreeModel::iterator& > signal_cursor_on_match();
190
dnl// Hook in custom callback.
191
dnl// It will use the callback.
193
_PUSH(SECTION_PCC_CLASS_INIT_DEFAULT_SIGNAL_HANDLERS)
194
klass->match_selected = &match_selected_callback_custom;
195
_SECTION(SECTION_PH_DEFAULT_SIGNAL_HANDLERS)
196
static gboolean match_selected_callback_custom(GtkEntryCompletion* self, GtkTreeModel* c_model, GtkTreeIter* c_iter);
200
#m4 _CONVERSION(`const char*',`const Glib::ustring&',__GCHARP_TO_USTRING)
203
/** Emitted when the inline autocompletion is triggered.
204
* The default behaviour is to make the entry display the
205
* whole prefix and select the newly inserted part.
207
* Applications may connect to this signal in order to insert only a
208
* smaller part of the @a prefix into the entry - e.g. the entry used in
209
* the FileChooser inserts only the part of the prefix up to the
214
* @param prefix The common prefix of all possible completions.
215
* @result true if the signal has been handled
217
_WRAP_SIGNAL(bool insert_prefix(const Glib::ustring& prefix), insert_prefix)
219
_WRAP_PROPERTY("model", Glib::RefPtr<Gtk::TreeModel>)
220
_WRAP_PROPERTY("minimum_key_length", int)
221
_WRAP_PROPERTY("text_column, int)
222
_WRAP_PROPERTY("inline_completion", bool)
223
_WRAP_PROPERTY("popup_completion", bool)
224
_WRAP_PROPERTY("popup_set_width", bool)
225
_WRAP_PROPERTY("popup_single_match", bool)
226
_WRAP_PROPERTY("inline-selection", bool)
227
_WRAP_PROPERTY("cell-area", Glib::RefPtr<CellArea>)
231
//Default Signal Handler:
232
virtual bool on_match_selected(const TreeModel::iterator& iter);
233
//No default handler for on_cursor_on_match(), to preserver ABI. TODO: Add this when we can break ABI.
added
removed
gtk/src/entrycompletion.hg
