callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move GtkEntryCompletion docs inline

Browse Source 
Based on a patch by Garrett Regier
https://bugzilla.gnome.org/show_bug.cgi?id=617322
This commit is contained in:
Matthias Clasen 2011-01-04 17:54:47 -05:00
parent 82c9013e01
commit 2690b8b924
3 changed files with 319 additions and 645 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

377
docs/reference/gtk/tmpl/gtkentrycompletion.sgml
View File

@ -1,377 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkEntryCompletion
<!-- ##### SECTION Short_Description ##### -->
Completion functionality for GtkEntry
<!-- ##### SECTION Long_Description ##### -->
<para>
#GtkEntryCompletion is an auxiliary object to be used in conjunction with
#GtkEntry to provide the completion functionality. It implements the
#GtkCellLayout interface, to allow the user to add extra cells to the
#GtkTreeView with completion matches.
</para>
<para>
"Completion functionality" means that when the user modifies the text
in the entry, #GtkEntryCompletion 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
gtk_entry_completion_set_text_column()), but this can be overridden with
a custom match function (see gtk_entry_completion_set_match_func()).
</para>
<para>
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.
</para>
<para>
To add completion functionality to an entry, use gtk_entry_set_completion().
</para>
<para>
In addition to regular completion matches, which will be inserted into the
entry when they are selected, #GtkEntryCompletion also allows 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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### STRUCT GtkEntryCompletion ##### -->
<para>
The GtkEntryCompletion struct contains only private data.
</para>
<!-- ##### SIGNAL GtkEntryCompletion::action-activated ##### -->
<para>
</para>
@entrycompletion: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GtkEntryCompletion::cursor-on-match ##### -->
<para>
</para>
@entrycompletion: the object which received the signal.
@arg1:
@arg2:
@Returns:
<!-- ##### SIGNAL GtkEntryCompletion::insert-prefix ##### -->
<para>
</para>
@entrycompletion: the object which received the signal.
@arg1:
@Returns:
<!-- ##### SIGNAL GtkEntryCompletion::match-selected ##### -->
<para>
</para>
@entrycompletion: the object which received the signal.
@arg1:
@arg2:
@Returns:
<!-- ##### ARG GtkEntryCompletion:inline-completion ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:inline-selection ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:minimum-key-length ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:model ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:popup-completion ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:popup-set-width ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:popup-single-match ##### -->
<para>
</para>
<!-- ##### ARG GtkEntryCompletion:text-column ##### -->
<para>
</para>
<!-- ##### USER_FUNCTION GtkEntryCompletionMatchFunc ##### -->
<para>
A function which decides whether the row indicated by @iter matches a given
@key, and should be displayed as a possible completion for @key. Note that
@key is normalized and case-folded (see g_utf8_normalize() and
g_utf8_casefold()). If this is not appropriate, match functions have access
to the unmodified key via <literal>gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry (<!-- -->)))</literal>.
</para>
@completion: the #GtkEntryCompletion
@key: the string to match, normalized and case-folded
@iter: a #GtkTreeIter indicating the row to match
@user_data: user data given to gtk_entry_completion_set_match_func()
@Returns: %TRUE if @iter should be displayed as a possible completion for @key
<!-- ##### FUNCTION gtk_entry_completion_new ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_get_entry ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_model ##### -->
<para>
</para>
@completion:
@model:
<!-- ##### FUNCTION gtk_entry_completion_get_model ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_match_func ##### -->
<para>
</para>
@completion:
@func:
@func_data:
@func_notify:
<!-- ##### FUNCTION gtk_entry_completion_set_minimum_key_length ##### -->
<para>
</para>
@completion:
@length:
<!-- ##### FUNCTION gtk_entry_completion_get_minimum_key_length ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_complete ##### -->
<para>
</para>
@completion:
<!-- ##### FUNCTION gtk_entry_completion_get_completion_prefix ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_insert_prefix ##### -->
<para>
</para>
@completion:
<!-- ##### FUNCTION gtk_entry_completion_insert_action_text ##### -->
<para>
</para>
@completion:
@index_:
@text:
<!-- ##### FUNCTION gtk_entry_completion_insert_action_markup ##### -->
<para>
</para>
@completion:
@index_:
@markup:
<!-- ##### FUNCTION gtk_entry_completion_delete_action ##### -->
<para>
</para>
@completion:
@index_:
<!-- ##### FUNCTION gtk_entry_completion_set_text_column ##### -->
<para>
</para>
@completion:
@column:
<!-- ##### FUNCTION gtk_entry_completion_get_text_column ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_inline_completion ##### -->
<para>
</para>
@completion:
@inline_completion:
<!-- ##### FUNCTION gtk_entry_completion_get_inline_completion ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_inline_selection ##### -->
<para>
</para>
@completion:
@inline_selection:
<!-- ##### FUNCTION gtk_entry_completion_get_inline_selection ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_popup_completion ##### -->
<para>
</para>
@completion:
@popup_completion:
<!-- ##### FUNCTION gtk_entry_completion_get_popup_completion ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_popup_set_width ##### -->
<para>
</para>
@completion:
@popup_set_width:
<!-- ##### FUNCTION gtk_entry_completion_get_popup_set_width ##### -->
<para>
</para>
@completion:
@Returns:
<!-- ##### FUNCTION gtk_entry_completion_set_popup_single_match ##### -->
<para>
</para>
@completion:
@popup_single_match:
<!-- ##### FUNCTION gtk_entry_completion_get_popup_single_match ##### -->
<para>
</para>
@completion:
@Returns:

118
gtk/gtkentrycompletion.c
View File

@ -17,6 +17,40 @@
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION:gtkentrycompletion
* @Short_description: Completion functionality for GtkEntry
* @Title: GtkEntryCompletion
*
* #GtkEntryCompletion is an auxiliary object to be used in conjunction with
* #GtkEntry to provide the completion functionality. It implements the
* #GtkCellLayout interface, to allow the user to add extra cells to the
* #GtkTreeView with completion matches.
*
* "Completion functionality" means that when the user modifies the text
* in the entry, #GtkEntryCompletion 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
* gtk_entry_completion_set_text_column()), but this can be overridden
* with a custom match function (see gtk_entry_completion_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 #GtkEntryCompletion::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, #GtkEntryCompletion also allows 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 #GtkEntryCompletion::action-activated signal is emitted.
*/
#include "config.h"
#include "gtkentrycompletion.h"
@ -367,7 +401,7 @@ gtk_entry_completion_class_init (GtkEntryCompletionClass *klass)
*
* Determines whether the possible completions on the popup
* will appear in the entry as you navigate through them.
*
* Since: 2.12
*/
g_object_class_install_property (object_class,
@ -981,7 +1015,7 @@ gtk_entry_completion_selection_changed (GtkTreeSelection *selection,
*
* Creates a new #GtkEntryCompletion object.
*
* Return value: A newly created #GtkEntryCompletion object.
* Return value: A newly created #GtkEntryCompletion object
*
* Since: 2.4
*/
@ -1003,7 +1037,7 @@ gtk_entry_completion_new (void)
* specified @area to layout cells in the underlying
* #GtkTreeViewColumn for the drop-down menu.
*
* Return value: A newly created #GtkEntryCompletion object.
* Return value: A newly created #GtkEntryCompletion object
*
* Since: 3.0
*/
@ -1019,11 +1053,11 @@ gtk_entry_completion_new_with_area (GtkCellArea *area)
/**
* gtk_entry_completion_get_entry:
* @completion: A #GtkEntryCompletion.
* @completion: a #GtkEntryCompletion
*
* Gets the entry @completion has been attached to.
*
* Return value: (transfer none): The entry @completion has been attached to.
* Return value: (transfer none): The entry @completion has been attached to
*
* Since: 2.4
*/
@ -1037,8 +1071,8 @@ gtk_entry_completion_get_entry (GtkEntryCompletion *completion)
/**
* gtk_entry_completion_set_model:
* @completion: A #GtkEntryCompletion.
* @model: (allow-none): The #GtkTreeModel.
* @completion: a #GtkEntryCompletion
* @model: (allow-none): the #GtkTreeModel
*
* Sets the model for a #GtkEntryCompletion. If @completion already has
* a model set, it will remove it before setting the new model.
@ -1082,13 +1116,13 @@ gtk_entry_completion_set_model (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_get_model:
* @completion: A #GtkEntryCompletion.
* @completion: a #GtkEntryCompletion
*
* Returns the model the #GtkEntryCompletion is using as data source.
* Returns %NULL if the model is unset.
*
* Return value: (transfer none): A #GtkTreeModel, or %NULL if none
* is currently being used.
* is currently being used
*
* Since: 2.4
*/
@ -1105,10 +1139,10 @@ gtk_entry_completion_get_model (GtkEntryCompletion *completion)
/**
* gtk_entry_completion_set_match_func:
* @completion: A #GtkEntryCompletion.
* @func: The #GtkEntryCompletionMatchFunc to use.
* @func_data: The user data for @func.
* @func_notify: Destroy notifier for @func_data.
* @completion: a #GtkEntryCompletion
* @func: the #GtkEntryCompletionMatchFunc to use
* @func_data: user data for @func
* @func_notify: destroy notify for @func_data.
*
* Sets the match function for @completion to be @func. The match function
* is used to determine if a row should or should not be in the completion
@ -1134,8 +1168,8 @@ gtk_entry_completion_set_match_func (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_set_minimum_key_length:
* @completion: A #GtkEntryCompletion.
* @length: The minimum length of the key in order to start completing.
* @completion: a #GtkEntryCompletion
* @length: the minimum length of the key in order to start completing
*
* Requires the length of the search key for @completion to be at least
* @length. This is useful for long lists, where completing using a small
@ -1161,11 +1195,11 @@ gtk_entry_completion_set_minimum_key_length (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_get_minimum_key_length:
* @completion: A #GtkEntryCompletion.
* @completion: a #GtkEntryCompletion
*
* Returns the minimum key length as set for @completion.
*
* Return value: The currently used minimum key length.
* Return value: The currently used minimum key length
*
* Since: 2.4
*/
@ -1179,7 +1213,7 @@ gtk_entry_completion_get_minimum_key_length (GtkEntryCompletion *completion)
/**
* gtk_entry_completion_complete:
* @completion: A #GtkEntryCompletion.
* @completion: a #GtkEntryCompletion
*
* Requests a completion operation, or in other words a refiltering of the
* current list with completions, using the current key. The completion list
@ -1240,9 +1274,9 @@ gtk_entry_completion_insert_action (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_insert_action_text:
* @completion: A #GtkEntryCompletion.
* @index_: The index of the item to insert.
* @text: Text of the item to insert.
* @completion: a #GtkEntryCompletion
* @index_: the index of the item to insert
* @text: text of the item to insert
*
* Inserts an action in @completion's action item list at position @index_
* with text @text. If you want the action item to have markup, use
@ -1263,9 +1297,9 @@ gtk_entry_completion_insert_action_text (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_insert_action_markup:
* @completion: A #GtkEntryCompletion.
* @index_: The index of the item to insert.
* @markup: Markup of the item to insert.
* @completion: a #GtkEntryCompletion
* @index_: the index of the item to insert
* @markup: markup of the item to insert
*
* Inserts an action in @completion's action item list at position @index_
* with markup @markup.
@ -1285,8 +1319,8 @@ gtk_entry_completion_insert_action_markup (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_delete_action:
* @completion: A #GtkEntryCompletion.
* @index_: The index of the item to Delete.
* @completion: a #GtkEntryCompletion
* @index_: the index of the item to delete
*
* Deletes the action at @index_ from @completion's action list.
*
@ -1308,8 +1342,8 @@ gtk_entry_completion_delete_action (GtkEntryCompletion *completion,
/**
* gtk_entry_completion_set_text_column:
* @completion: A #GtkEntryCompletion.
* @column: The column in the model of @completion to get strings from.
* @completion: a #GtkEntryCompletion
* @column: the column in the model of @completion to get strings from
*
* Convenience function for setting up the most used case of this code: a
* completion list with just strings. This function will set up @completion
@ -1318,7 +1352,8 @@ gtk_entry_completion_delete_action (GtkEntryCompletion *completion,
*
* This functions creates and adds a #GtkCellRendererText for the selected
* column. If you need to set the text column, but don't want the cell
* renderer, use g_object_set() to set the ::text_column property directly.
* renderer, use g_object_set() to set the #GtkEntryCompletion:text-column
* property directly.
*
* Since: 2.4
*/
@ -1352,7 +1387,7 @@ gtk_entry_completion_set_text_column (GtkEntryCompletion *completion,
* Return value: the column containing the strings
*
* Since: 2.6
**/
*/
gint
gtk_entry_completion_get_text_column (GtkEntryCompletion *completion)
{
@ -1727,7 +1762,7 @@ gtk_entry_completion_real_insert_prefix (GtkEntryCompletion *completion,
* Returns: the prefix for the current completion
*
* Since: 2.12
**/
*/
const gchar*
gtk_entry_completion_get_completion_prefix (GtkEntryCompletion *completion)
{
@ -1791,8 +1826,7 @@ gtk_entry_completion_insert_completion (GtkEntryCompletion *completion,
* Requests a prefix insertion.
*
* Since: 2.6
**/
*/
void
gtk_entry_completion_insert_prefix (GtkEntryCompletion *completion)
{
@ -1825,7 +1859,7 @@ gtk_entry_completion_insert_prefix (GtkEntryCompletion *completion)
* be automatically inserted in the entry.
*
* Since: 2.6
**/
*/
void
gtk_entry_completion_set_inline_completion (GtkEntryCompletion *completion,
gboolean inline_completion)
@ -1852,7 +1886,7 @@ gtk_entry_completion_set_inline_completion (GtkEntryCompletion *completion,
* Return value: %TRUE if inline completion is turned on
*
* Since: 2.6
**/
*/
gboolean
gtk_entry_completion_get_inline_completion (GtkEntryCompletion *completion)
{
@ -1869,7 +1903,7 @@ gtk_entry_completion_get_inline_completion (GtkEntryCompletion *completion)
* Sets whether the completions should be presented in a popup window.
*
* Since: 2.6
**/
*/
void
gtk_entry_completion_set_popup_completion (GtkEntryCompletion *completion,
gboolean popup_completion)
@ -1896,7 +1930,7 @@ gtk_entry_completion_set_popup_completion (GtkEntryCompletion *completion,
* Return value: %TRUE if popup completion is turned on
*
* Since: 2.6
**/
*/
gboolean
gtk_entry_completion_get_popup_completion (GtkEntryCompletion *completion)
{
@ -1942,7 +1976,7 @@ gtk_entry_completion_set_popup_set_width (GtkEntryCompletion *completion,
* the entry
*
* Since: 2.8
**/
*/
gboolean
gtk_entry_completion_get_popup_set_width (GtkEntryCompletion *completion)
{
@ -1989,10 +2023,10 @@ gtk_entry_completion_set_popup_single_match (GtkEntryCompletion *completion,
* only a single match.
*
* Return value: %TRUE if the popup window will appear regardless of the
* number of matches.
* number of matches
*
* Since: 2.8
**/
*/
gboolean
gtk_entry_completion_get_popup_single_match (GtkEntryCompletion *completion)
{
@ -2010,7 +2044,7 @@ gtk_entry_completion_get_popup_single_match (GtkEntryCompletion *completion)
* inside the entry.
*
* Since: 2.12
**/
*/
void
gtk_entry_completion_set_inline_selection (GtkEntryCompletion *completion,
gboolean inline_selection)
@ -2036,7 +2070,7 @@ gtk_entry_completion_set_inline_selection (GtkEntryCompletion *completion,
* Returns: %TRUE if inline-selection mode is on
*
* Since: 2.12
**/
*/
gboolean
gtk_entry_completion_get_inline_selection (GtkEntryCompletion *completion)
{

17
gtk/gtkentrycompletion.h
View File

@ -43,6 +43,23 @@ typedef struct _GtkEntryCompletion GtkEntryCompletion;
typedef struct _GtkEntryCompletionClass GtkEntryCompletionClass;
typedef struct _GtkEntryCompletionPrivate GtkEntryCompletionPrivate;
/**
* GtkEntryCompletionMatchFunc:
* @completion: the #GtkEntryCompletion
* @key: the string to match, normalized and case-folded
* @iter: a #GtkTreeIter indicating the row to match
* @user_data: user data given to gtk_entry_completion_set_match_func()
*
* A function which decides whether the row indicated by @iter matches
* a given @key, and should be displayed as a possible completion for @key.
* Note that @key is normalized and case-folded (see g_utf8_normalize()
* and g_utf8_casefold()). If this is not appropriate, match functions
* have access to the unmodified key via
* <literal>gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry (<!-- -->)))</literal>.
*
* Returns: %TRUE if @iter should be displayed as a possible completion
* for @key
*/
typedef gboolean (* GtkEntryCompletionMatchFunc) (GtkEntryCompletion *completion,
const gchar *key,
GtkTreeIter *iter,