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:

List of all members.

## Signal Prototypes

- const MatchSelectedSignalType match_selected_signal
    Match selected signal (see signal_match_selected()).
- const ActionActivatedSignalType action_activated_signal
    Action activated selected signal (see signal_action_activated()).
- const InsertPrefixSignalType insert_prefix_signal
    Insert prefix signal (see signal_insert_prefix()).

## Public Types

- typedef sigc::slot< bool,
  const String &, const TreeIter & > 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.

## Public Member Functions

Constructors

- EntryCompletion ()
    Constructs a new entry completion object with a reference count of 1 that the caller owns.
- EntryCompletion (TreeModel &model)
    Constructs a new entry completion object that uses the specified model.
- virtual ~EntryCompletion ()
    Destructor.

Accessors

- GtkEntryCompletion * gtk_entry_completion () const
    Get a pointer to the GtkEntryCompletion structure.
- operator GtkEntryCompletion * () const
    Conversion operator; safely converts an EntryCompletion to a GtkEntryCompletion pointer.
- Entry * get_entry () const
    Gets the entry widget the completion has been attached to.
- TreeModel * get_model () const
    Gets the model the entry completion is using as a data source.
- int get_minimum_key_length () const
    Gets the minimum key length as set for completion.
- bool get_inline_completion () const
    Determines whether the common prefix of the possible completions should be automatically inserted in the entry.
- bool get_popup_completion () const
    Determines whether the completions should be presented in a popup window.
- int get_text_column () const
    Gets the column in the model of completion to get strings from.

Methods

- void set_model (TreeModel &model)
    Sets the model for the entry completion.
- void set_match_func (const MatchSlot &slot)
    Sets the match callback slot for completion to be slot.
- void set_minimum_key_length (int length)
    Requires the length of the search key for completion to be at least length.
- void complete ()
    Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key.
- void insert_prefix ()
    Requests a prefix insertion.
- void insert_action_text (int index, const String &text)
    Inserts an action in completion's action item list at position index with text text.
- void insert_action_markup (int index, const String &markup)
    Inserts an action in completion's action item list at position index with markup markup.
- void delete_action (int index)
    Deletes the action at index from completion's action list.
- void set_inline_completion (bool inline_completion)
    Sets whether the common prefix of the possible completions should be automatically inserted in the entry.
- void set_popup_completion (bool popup_completion)
    Sets whether the completions should be presented in a popup window.
- void set_text_column (int column)
    A convenience method for setting up the most used case of this code: a completion list with just strings.

Signal Proxies

- const MatchSelectedSignalProxy signal_match_selected ()
    Connect to the match_selected_signal; emitted when a match from the list is selected.
- const ActionActivatedSignalProxy signal_action_activated ()
    Connect to the action_activated_signal; emitted when an action is activated.
- const InsertPrefixSignalProxy signal_insert_prefix ()
    Connect to the insert_prefix_signal; emitted when the inline autocompletion is triggered.

## Protected Member Functions

Constructors

- EntryCompletion (GtkEntryCompletion *completion, bool owns_reference=true)
    Construct a new EntryCompletion from an existing GtkEntryCompletion.

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

- entrycompletion.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3