![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
Automatic String CompletionAutomatic String Completion — support for automatic completion using a group of target strings |
#include <glib.h> GCompletion; GCompletion* g_completion_new (GCompletionFunc func); gchar * (*GCompletionFunc) (gpointer ); void g_completion_add_items (GCompletion *cmp, GList *items); void g_completion_remove_items (GCompletion *cmp, GList *items); void g_completion_clear_items (GCompletion *cmp); GList* g_completion_complete (GCompletion *cmp, const gchar *prefix, gchar **new_prefix); GList* g_completion_complete_utf8 (GCompletion *cmp, const gchar *prefix, gchar **new_prefix); void g_completion_set_compare (GCompletion *cmp, GCompletionStrncmpFunc strncmp_func); gint (*GCompletionStrncmpFunc) (const gchar *s1, const gchar *s2, gsize n); void g_completion_free (GCompletion *cmp);
GCompletion provides support for automatic completion of a string using any group of target strings. It is typically used for file name completion as is common in many UNIX shells.
A GCompletion is created using g_completion_new()
.
Target items are added and removed with
g_completion_add_items()
, g_completion_remove_items()
and
g_completion_clear_items()
.
A completion attempt is requested with g_completion_complete()
or
g_completion_complete_utf8()
.
When no longer needed, the GCompletion is freed with g_completion_free()
.
Items in the completion can be simple strings (e.g. filenames),
or pointers to arbitrary data structures. If data structures are used
you must provide a GCompletionFunc in g_completion_new()
,
which retrieves the item's string from the data structure.
You can change the way in which strings are compared by setting
a different GCompletionStrncmpFunc in g_completion_set_compare()
.
typedef struct { GList* items; GCompletionFunc func; gchar* prefix; GList* cache; GCompletionStrncmpFunc strncmp_func; } GCompletion;
The data structure used for automatic completion.
GList * |
list of target items (strings or data structures). |
GCompletionFunc |
function which is called to get the string associated with a target
item. It is NULL if the target items are strings.
|
gchar * |
the last prefix passed to g_completion_complete() or
g_completion_complete_utf8() .
|
GList * |
the list of items which begin with prefix .
|
GCompletionStrncmpFunc |
The function to use when comparing strings.
Use g_completion_set_compare() to modify this function.
|
GCompletion* g_completion_new (GCompletionFunc func);
Creates a new GCompletion.
|
the function to be called to return the string representing an item
in the GCompletion, or NULL if strings are going to be used as the
GCompletion items.
|
Returns : |
the new GCompletion. |
gchar * (*GCompletionFunc) (gpointer );
Specifies the type of the function passed to g_completion_new()
.
It should return the string corresponding to the given target item.
This is used when you use data structures as GCompletion items.
|
the completion item. |
Returns : |
the string corresponding to the item. |
void g_completion_add_items (GCompletion *cmp, GList *items);
Adds items to the GCompletion.
|
the GCompletion. |
|
the list of items to add. |
void g_completion_remove_items (GCompletion *cmp, GList *items);
Removes items from a GCompletion.
|
the GCompletion. |
|
the items to remove. |
void g_completion_clear_items (GCompletion *cmp);
Removes all items from the GCompletion.
|
the GCompletion. |
GList* g_completion_complete (GCompletion *cmp, const gchar *prefix, gchar **new_prefix);
Attempts to complete the string prefix
using the GCompletion target items.
|
the GCompletion. |
|
the prefix string, typically typed by the user, which is compared with each of the items. |
|
if non-NULL , returns the longest prefix which is common to all
items that matched prefix , or NULL if no items matched prefix .
This string should be freed when no longer needed.
|
Returns : |
the list of items whose strings begin with prefix . This should
not be changed.
|
GList* g_completion_complete_utf8 (GCompletion *cmp, const gchar *prefix, gchar **new_prefix);
Attempts to complete the string prefix
using the GCompletion target items.
In contrast to g_completion_complete()
, this function returns the largest common
prefix that is a valid UTF-8 string, omitting a possible common partial
character.
You should use this function instead of g_completion_complete()
if your
items are UTF-8 strings.
|
the GCompletion |
|
the prefix string, typically used by the user, which is compared with each of the items |
|
if non-NULL , returns the longest prefix which is common to all
items that matched prefix , or NULL if no items matched prefix .
This string should be freed when no longer needed.
|
Returns : |
the list of items whose strings begin with prefix . This should
not be changed.
|
Since 2.4
void g_completion_set_compare (GCompletion *cmp, GCompletionStrncmpFunc strncmp_func);
Sets the function to use for string comparisons. The default
string comparison function is strncmp()
.
|
a GCompletion. |
|
the string comparison function. |
gint (*GCompletionStrncmpFunc) (const gchar *s1, const gchar *s2, gsize n);
Specifies the type of the function passed to g_completion_set_compare()
.
This is used when you use strings as GCompletion items.
|
string to compare with s2 .
|
|
string to compare with s1 .
|
|
maximal number of bytes to compare. |
Returns : |
an integer less than, equal to, or greater than zero if the
first n bytes of s1 is found, respectively, to be less than, to match,
or to be greater than the first n bytes of s2 .
|
void g_completion_free (GCompletion *cmp);
Frees all memory used by the GCompletion.
|
the GCompletion. |