Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gtk::EntryCompletion Class Reference

A GtkEntryCompletion C++ wrapper class. More...

#include <xfc/gtk/entrycompletion.hh>

Inheritance diagram for Xfc::Gtk::EntryCompletion:

Xfc::G::Object Xfc::Gtk::CellLayout Xfc::G::TypeInstance Xfc::G::TypeInterface Xfc::Trackable Xfc::G::TypeInstance Xfc::Trackable List of all members.

Signal Prototypes

Public Types

Public Member Functions

Constructors
Accessors
Methods
Signal Proxies

Protected Member Functions

Constructors

Detailed Description

A GtkEntryCompletion C++ wrapper class.

EntryCompletion is an auxiliary object to be used in conjunction with Gtk::Entry to provide the completion functionality. It implements the Gtk::CellLayout interface to allow the user to add extra cells to the Gtk::TreeView with completion matches.

"Completion functionality" means that when the user modifies the text in the entry, EntryCompletion checks which rows in the model match the current content of the entry, and displays a list of matches. By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see set_text_column()), but this can be overridden with a custom match function (see set_match_func()).

When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the "match_selected" signal and updating the entry in the signal handler. Note that you should return true from the signal handler to suppress the default behaviour.

To add completion functionality to an entry, use Gtk::Entry::set_completion(). In addition to regular completion matches, which will be inserted into the entry when they are selected, EntryCompletion also allows you to display 'actions' in the popup window. Their appearance is similar to menuitems, to differentiate them clearly from completion strings. When an action is selected, the "action_activated" signal is emitted.

Note: dynamically allocated objects must either be unreferenced or assigned to a smart pointer. Stack objects are automatically unreferenced when they go out of scope.

See also: the Entry Completion HOWTO and example, and the entry completion example in the <tests/entrycompletion> subdirectory.

Member Typedef Documentation

typedef sigc::slot<bool, const String&, const TreeIter&> Xfc::Gtk::EntryCompletion::MatchSlot
 

Signature of the callback slot to be called the row indicated by the TreeIter matches a given key, and should be displayed as a possible completion for key.

Example: Method signature for MatchSlot. 

             bool method(const String& key, const TreeIter& iter);
             // key: The string to match.
             // iter: A TreeIter indicating indicating the row to match.
             // return: <EM>true</EM> if <EM>iter</EM> should be displayed as a possible completion for <EM>key</EM>.

Constructor & Destructor Documentation

Xfc::Gtk::EntryCompletion::EntryCompletion (  GtkEntryCompletion *  completion,
bool  owns_reference = true
)  [explicit, protected]
 

Construct a new EntryCompletion from an existing GtkEntryCompletion.

Parameters:
completion A pointer to a GtkEntryCompletion.
owns_reference Set false if the initial reference count is floating, set true if it's not.
The completion can be a newly created GtkEntryCompletion or an existing GtkEntryCompletion (see G::Object::Object).

Xfc::Gtk::EntryCompletion::EntryCompletion (  TreeModel &  model  ) 
 

Constructs a new entry completion object that uses the specified model.

Parameters:
model The model for the entry completion.
The new entry completion has a reference count of 1 that the caller owns.

Member Function Documentation

void Xfc::Gtk::EntryCompletion::complete (   ) 
 

Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key.

The completion list view will be updated accordingly.

Entry* Xfc::Gtk::EntryCompletion::get_entry (   )  const
 

Gets the entry widget the completion has been attached to.

Returns:
The entry widget the completion is attached to.

bool Xfc::Gtk::EntryCompletion::get_inline_completion (   )  const
 

Determines whether the common prefix of the possible completions should be automatically inserted in the entry.

Returns:
true if inline completion is turned on.

int Xfc::Gtk::EntryCompletion::get_minimum_key_length (   )  const
 

Gets the minimum key length as set for completion.

Returns:
The currently used minimum key length.

TreeModel* Xfc::Gtk::EntryCompletion::get_model (   )  const
 

Gets the model the entry completion is using as a data source.

Returns:
A Gtk::TreeModel, or null if none is currently being used.

bool Xfc::Gtk::EntryCompletion::get_popup_completion (   )  const
 

Determines whether the completions should be presented in a popup window.

Returns:
true if popup completion is turned on.

int Xfc::Gtk::EntryCompletion::get_text_column (   )  const
 

Gets the column in the model of completion to get strings from.

Returns:
The column containing the strings.

void Xfc::Gtk::EntryCompletion::insert_action_markup (  int  index,
const String &  markup
) 
 

Inserts an action in completion's action item list at position index with markup markup.

Parameters:
index The index of the item to insert.
markup The markup of the item to insert.

void Xfc::Gtk::EntryCompletion::insert_action_text (  int  index,
const String &  text
) 
 

Inserts an action in completion's action item list at position index with text text.

Parameters:
index The index of the item to insert.
text The text of the item to insert.
If you want the action item to have markup, use insert_action_markup().

void Xfc::Gtk::EntryCompletion::set_inline_completion (  bool  inline_completion  ) 
 

Sets whether the common prefix of the possible completions should be automatically inserted in the entry.

Parameters:
inline_completion Set to true to do inline completion.

void Xfc::Gtk::EntryCompletion::set_match_func (  const MatchSlot &  slot  ) 
 

Sets the match callback slot for completion to be slot.

Parameters:
slot The MatchSlot to use.
The match slot is used to determine if a row should or should not be in the completion list.

void Xfc::Gtk::EntryCompletion::set_minimum_key_length (  int  length  ) 
 

Requires the length of the search key for completion to be at least length.

Parameters:
length The minimum length of the key in order to start completing.
This is useful for long lists, where completing using a small key takes a lot of time and will come up with meaningless results anyway (ie, a too large dataset).

void Xfc::Gtk::EntryCompletion::set_model (  TreeModel &  model  ) 
 

Sets the model for the entry completion.

Parameters:
model The Gtk::TreeModel.
If the completion already has a model set, it will remove it before setting the new model.

void Xfc::Gtk::EntryCompletion::set_popup_completion (  bool  popup_completion  ) 
 

Sets whether the completions should be presented in a popup window.

Parameters:
popup_completion Set to true to do popup completion.

void Xfc::Gtk::EntryCompletion::set_text_column (  int  column  ) 
 

A convenience method for setting up the most used case of this code: a completion list with just strings.

Parameters:
column The column in the model of completion to get strings from.
This method will set up the completion to have a list displaying all (and just) strings in the completion list, and to get those strings from column in the model of completion. It creates and adds a Gtk::CellRendererText for the selected column.

Member Data Documentation

const ActionActivatedSignalType Xfc::Gtk::EntryCompletion::action_activated_signal [static, protected]
 

Action activated selected signal (see signal_action_activated()).

Calls a slot with the signature: 

             void function(const TreeModel& model, const TreeIter& iter);
             // index: The index of the activated action.

const InsertPrefixSignalType Xfc::Gtk::EntryCompletion::insert_prefix_signal [static, protected]
 

Insert prefix signal (see signal_insert_prefix()).

Calls a slot with the signature: 

             bool function(const String& prefix);
             @param prefix The common prefix of all possible completions.
             @return <EM>true</EM> if the signal has been handled.

The default behaviour is to make the entry display the whole prefix and select the newly inserted part. Applications may connect to this signal in order to insert only a smaller part of the prefix into the entry - e.g. the entry used in Gtk::FileChooser inserts only the part of the prefix up to the next '/'.

const MatchSelectedSignalType Xfc::Gtk::EntryCompletion::match_selected_signal [static, protected]
 

Match selected signal (see signal_match_selected()).

Calls a slot with the signature: 

             bool function(const TreeModel& model, const TreeIter& iter);
             // model: The Gtk::TreeModel containing the matches.
             // iter: A Gtk::TreeIter positioned at the selected match.
             // return: true if the signal has been handled.

The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3